mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-04-15 10:55:37 +00:00
a7c4d606ee
* Added page about moving/renaming docs, new headings for readme * added navigation section * revised README * revised moving-or-renaming-docs * Apply suggestions from code review Co-authored-by: Lucas Saintarbor <lucas.saintarbor@suse.com> * Update moving-or-renaming-docs.md - revamping schema example * json > js * typos, extra explanation * json > js * various changes --------- Co-authored-by: Lucas Saintarbor <lucas.saintarbor@suse.com>
68 lines
3.2 KiB
Markdown
68 lines
3.2 KiB
Markdown
# 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.
|