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).
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:
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.
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.
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:
{
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.