Configure navigation on the sidebar
The sidebar is automatically generated based on your project's file structure, with index.md
file as the first item, and the rest following the folder and file names in the natural sort order. However, you can customize your project's navigation by configuring the order and titles of items in your sidebar using the sidebars.yaml
file. You can also hide the sidebar, add multiple sidebars, and add the sidebar for pages not listed in a sidebars.yaml
file.
Customize link titles and the order of links in the sidebar
To customize the link titles and order of links in your sidebar:
- Create a
sidebars.yaml
file and add it to the root of your project.
You can add prefixes to sidebar file names to make them more distinct. Sidebar files are valid as long as they end insidebars.yaml
. - Add the
page
option with the value of the file path or thehref
option with the value for the URL for the item you are including. For example, the following configuration adds a sidebar with a link to the Markdown pageindex.md
with the first heading on that page as link text and a link tohttp://example.com
with the URL as the link text:sidebars.yaml- page: index.md - href: http://example.com
- (Optional): Add the following options:
label
: This option is the link text that appears on the sidebar for the page. If you don't include it, the first heading of the Markdown page will be used for thepage
option, or the value for thehref
option will be used.labelTranslationKey
: This option is used if you are translating the link text into a different language. See Localize labels using translation keys for more information.external
: This option causes a new tab to open when the user clicks the item in the sidebar. This option isfalse
by default. For example, the following configuration adds a sidebar with a link to the Markdown pageindex.md
with "Introduction" link text andsidebar.intro
translation key, and a link to the Markdown pagequickstart.md
with "Quickstart" link text that opens in a separate tab when selected:sidebars.yaml- page: index.md label: Introduction labelTranslationKey: sidebar.intro - page: quickstart.md label: Quickstart external: true
Compose a single sidebar from multiple sidebars.yaml
files
Another way to manage the sidebar in your project is to have a single main sidebar composed of multiple sidebars.yaml
files. This method is useful when you want to manage navigation by sections, or when some content comes from a remote content source.
To compose a sidebar from multiple sidebars.yaml
files:
- In your project's documentation folders, create one
sidebars.yaml
file per folder. For example, the following file structure includessidebars.yaml
files in the in root as well as the other content folders:Example file structure with sidebars.yaml files in each product folder├── get-started │ ├── index.md │ ├── install.md │ └── sidebars.yaml ├── configuration │ ├── index.md │ ├── interface.md │ ├── connectivity.md │ └── sidebars.yaml ├── museum-API │ ├── index.md │ ├── museum.yaml │ └── ├── payments-API │ ├── index.md │ ├── payments.yaml │ └── ├── index.md ├── redocly.yaml └── sidebars.yaml
- In each
sidebars.yaml
file in your content folders, add page entries to documentation and API description files. For example, the followingsidebars.yaml
file includes links to a Markdown document and an API description file:museum.sidebars.yaml- page: index.md label: Get started - page: museum.yaml label: Museum API
- In the
sidebars.yaml
file at the root of your project, for each componentsidebars.yaml
file, add an$ref:
followed by a link to asidebars.yaml
file in a content folder. For example, the followingsidebars.yaml
file includes four references to different sidebar files:sidebars.yaml- page: index.md label: Main page - $ref: get-started/sidebars.yaml - $ref: configuration/sidebars.yaml - $ref: museum-api/museum.sidebars.yaml - $ref: payments-api/payments.sidebars.yaml
After you build your project, the root sidebars.yaml
file combines all referenced pages and sidebar files into a single sidebar menu. This sidebar appears on all the pages it links to.
Add multiple sidebars
In larger projects, having a single sidebar with links to every content page can reduce the usability of your project. To prevent having an overly long sidebar, you can have a sidebar for each collection of content in your project, and the sidebar on the home page of your project with links to each landing page for the different sections. When users select an item on the home page sidebar, the page opens and updates the sidebar to reflect the sidebar for that collection.
To add multiple sidebars to your project:
- Create a folder for each collection of content. For example, the following file structure includes folders for get-started, configuration, and two APIs' reference documentation:Example file structure with multiple content collections
├── get-started │ ├── index.md │ └── install.md ├── configuration │ ├── index.md │ ├── interface.md │ └── connectivity.md ├── museum-API │ ├── index.md │ └── museum.yaml ├── payments-API │ ├── index.md │ └── payments.yaml ├── index.md ├── redocly.yaml └── sidebars.yaml
- In each content folder, add a
sidebars.yaml
file. For example, the following file structure contains asidebars.yaml
file in each content folder:Example file structure with sidebars.yaml files in each product folder├── get-started │ ├── index.md │ ├── install.md │ └── sidebars.yaml ├── configuration │ ├── index.md │ ├── interface.md │ ├── connectivity.md │ └── sidebars.yaml ├── museum-API │ ├── index.md │ ├── museum.yaml │ └── ├── payments-API │ ├── index.md │ ├── payments.yaml │ └── ├── index.md ├── redocly.yaml └── sidebars.yaml
- In each
sidebars.yaml
file in your content folders, add page entries to documentation and API description files. For example, the followingsidebars.yaml
file includes links to a Markdown document and an API description file:museum.sidebars.yaml- page: index.md label: Get started - page: museum.yaml label: Museum API
- In the
sidebars.yaml
file at the root of your project, add page entries for the landing pages in each content folder. The following is an examplesidebars.yaml
file in the root of a project with entries for the landing pages:sidebars.yaml- page: ./get-started/index.md label: Get started - page: ./configuration/index.md.md label: Configuration - page: ./museum-API/index.md label: Museum - page: ./payments-API/index.md label: Payments
Add a sidebar to a single page
Add a sidebar to a Markdown or React page by adding a relative path to a sidebars.yaml
file in the page's front matter. This configuration sets a page's sidebar even if that page isn't listed in the sidebars.yaml
file.
The following example uses the front matter to add a sidebar to a Markdown page using front matter:
--- sidebar: ./sidebars.yaml --- # Example page
The following example uses the front matter to add a sidebar to a React page using front matter:
import React from 'react'; export const frontmatter = { sidebar: '../sidebars.yaml', };
Related how-tos
- Hide the sidebar using the sidebar configuration.
- Check the sidebar reference for all configuration options and more examples.
- Control group-level permissions using RBAC in the sidebar.