diff --git a/README.md b/README.md index ddcf0d0a4fc..1812e0d86f7 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,31 @@ -# Edit The Docs +# Contribute to Rancher Docs -To get started, fork and clone the rancher-docs repository. +Welcome to the [Rancher docs](https://ranchermanager.docs.rancher.com/) repository. See the [Rancher software](https://github.com/rancher/rancher) repository if you have questions or requests for the Rancher platform. + +## Make a Suggestion + +You can suggest changes to the Rancher docs in two ways: + +1. [Open an issue](https://github.com/rancher/rancher-docs/issues/new/choose). +1. Edit the docs in the way you see fit and open a pull request. + +## Edit the Docs + +To get started, [fork](https://github.com/rancher/rancher-docs/fork) and clone the rancher-docs repository. Our repository doesn't allow you to make changes directly to the `main` branch. Create a working branch and make pull requests from your fork to [rancher/rancher-docs](https://github.com/rancher/rancher-docs). For most updates, you'll need to edit a file in `/docs`, and the corresponding file in `/versioned_docs/version-2.7`. If a change affects older versions, you can find files documenting Rancher v2.0 and later in the `/versioned_docs` directory. -If a file is moved or renamed, you'll also need to edit the `sidebars.js` files for each version, and the list of redirects in `docusaurus.config.js`. +If a file is moved or renamed, you'll also need to edit the `sidebars.js` files for each version, and the list of redirects in `docusaurus.config.js`. See [Moving or Renaming Docs](./moving-or-renaming-docs.md). -## Style & Formatting +### Navigate the Repo -The docs are written in [Markdown](https://www.markdownguide.org/getting-started/). We refer to the Microsoft [style guide](https://learn.microsoft.com/en-us/style-guide/welcome/) and generally use standard American English. Many pages are also available in Simplified Chinese. +The file paths in the repo correspond to the URLs for pages on the docs website. The docs for the latest version of Rancher are located in `/docs`. Most index pages are found within the `/pages-for-subheaders` directory in `/docs`. All images are in `/static/img` in the top level of the repo. Older docs are found within `/versioned_docs` and generally follow the same structure as the files in `/docs`. + +### Style & Formatting + +The docs are written in [Markdown](https://www.markdownguide.org/getting-started/). We refer to the Microsoft [style guide](https://learn.microsoft.com/en-us/style-guide/welcome/) and use standard American English. Many pages are also available in Simplified Chinese. Every docs page contain metadata in the first few lines: @@ -22,7 +37,7 @@ title: Some Title The `title` is rendered as the page's headline. The site renderer wraps the `title` value in `H1` tags, which are equivalent to `#` in Markdown syntax. This means that all subsequent headers on the page should be second level (`##`) or more. -## Docs Website +## Run the Docs Website The Rancher Docs website is built with [Docusaurus 2](https://docusaurus.io/), a modern static website generator. diff --git a/moving-or-renaming-docs.md b/moving-or-renaming-docs.md new file mode 100644 index 00000000000..2f0d1c5b0d1 --- /dev/null +++ b/moving-or-renaming-docs.md @@ -0,0 +1,67 @@ +# Adding, Moving, or Renaming Docs + +Docusaurus generates sidebars based on a JSON file named `sidebars.js`. When you add a new doc, you need to add an entry to `sidebars.js`. Otherwise, the page won't appear in the list of sidebar topics. When you move or re-title a doc, you need to update `sidebars.js` to reflect the change to the doc's location or title. If you alter a docs file's path, by moving the file or editing the file's name, you'll also need to add a redirect to the new path in `docusaurus.config.js`. + +> **Note:** Avoid adding filenames that contain periods before the file extension (example: `rke2-self-assessment-guide-with-cis-v1.23-k8s-v1.25.md`). If necessary, use dashes instead of periods (`rke2-self-assessment-guide-with-cis-v1-23-k8s-v1-25.md`). + +## Sidebars + +The `sidebars.js` file for the latest version of Rancher is located in the top level of the repo. Versioned docs each have their own versioned sidebar, found within `/versioned_sidebars` in the top level of the repo. + +The schema for `sidebars.js` looks like this: + +```JS +sidebar: [ + "toplevel", + { + type: "category", + label: "Second Level", + items: [ + "second-level/overview", + { + type: "category", + label: "Topic One", + link: { + type: "doc", + id: "pages-for-subheaders/index-page-for-topic-one" + } + items: [ + "second-level/topic-one/page-a", + "second-level/topic-one/page-b", + ] + } + ] + } +] +``` + +Paths for docs files are listed within an `items` array. Their position within the file is similar to how they'll be organized within the published sidebar. + +If the doc is as an index page for a topic with numerous subtopic pages, its entry in `sidebars.js` should have extra metadata, such as `category`, `link`, and `label`. + +### Moving Index Pages + +Some entries in the published sidebar are clickable dropdown menus. When a reader clicks them, they reveal a list of subtopics. These dropdown menu entries are indicated by `type: category` in the sidebar file. When you select the entry on the published docs site, the menu opens and you will navigate to the page indicated in `link.id`. + +Docusaurus uses the `label` field to generate the text that appears on the dropdown menu in the sidebar. When you rename these index pages, you also need to update their `label` in the sidebar file. + +### Redirecting Pages + +When you move a page, update redirects in the `@docusaurus/plugin-client-redirects` field within the `docusaurus.config.js` file. This file is located in the top level of the repo. + +The schema for docs redirects looks like this: + +```JS + { + to: '/faq/general-faq', + from: '/faq' + } + { + to: '/v2.6/faq/general-faq', + from: '/v2.6/faq' + }, +``` + +Docusaurus redirects don't accept wildcards, so each path must be exact. This means that you must add individual redirects for each version of a doc. + +Docusaurus also can't redirect pages whose filenames contain a period before the extension. You'll need to manually update any docset links to those pages.