Configure navigation on the sidebar
The sidebar is automatically generated based on your portal's file structure; however, you can configure navigation by customizing the order and titles of items in your sidebar using the sidebars.yaml
file. You can also hide the sidebar, add multiple sidebars, and set the sidebar for pages not listed in a sidebars.yaml
file.
Customize order and link titles
To customize the order and link titles of your sidebar:
- Create a
sidebars.yaml
file and add it to the root of your project. - 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 pageintro.md
with the first heading on that page as link text and a link tohttp://example.com
with the URL as the link text:- page: intro.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 Configure localization 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 pageintro.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:- page: intro.md label: Introduction labelTranslationKey: sidebar.intro - page: quickstart.md label: Quickstart external: true
Split sidebar configuration
If you want to split up the sidebar definition into multiple files, Redocly provides functionality to include a sidebar fragment into another sidebar. This is useful when you want to manage navigation by sections, or when some content comes from a remote content source.
To split a sidebar:
- Create a
sidebars.yaml
file and add it to the root of your project. - Add some sidebar configuration to
sidebars.yaml
. For example the following configuration adds two pages to the sidebar:- page: intro.md label: Introduction - page: quickstart.md label: Quickstart
- Create a second YAML file and add more sidebar configuration to this second file. This YAML file can have any name and can be added in a subdirectory if you wish. For example, a file named
topic-sidebars.yaml
adding a group and topic overview page:- group: Special topic page: topic/index.md items: - page: topic/overview.md
- In
sidebars.yaml
, add an entry with$ref
to point to thetopic-sidebars.yaml
file (including the directory path if applicable):- $ref: ./topic-sidebars.yaml
- The sidebar displays the content from the
topic-sidebars.yaml
file at the point that the$ref
entry is added in the navigation list.
Add multiple sidebars
To prevent having an overly long sidebar, you can have multiple sidebars in your portal.
In your root sidebars file include links to the landing pages for the different products or feature sets. Then in the folders for each product or feature set, include a sidebars file with the remaining content.
To add multiple sidebars:
- Create a folder for each collection of content. For example, a folder for each product:
dev_portal ├── product-1 ├── product-2 ├── product-3 ├── product-4 ├── redocly.yaml └── sidebars.yaml
- Add the content for each collection to the folders. A sample file structure:
dev_portal ├── product-1 │ ├── intro.md │ ├── install.md │ └── quickstart.md ├── product-2 │ ├── intro.md │ └── quickstart.md ├── product-3 │ ├── intro.md │ ├── install.md │ └── quickstart.md ├── product-4 │ ├── intro.md │ └── command_reference.md ├── redocly.yaml └── sidebars.yaml
- In the folder for each product, add a sidebars file. A sample file structure:Sample
dev_portal ├── product-1 │ ├── intro.md │ ├── install.md │ ├── quickstart.md │ └── sidebars.yaml ├── product-2 │ ├── intro.md │ ├── quickstart.md │ └── sidebars.yaml ├── product-3 │ ├── intro.md │ ├── install.md │ ├── quickstart.md │ └── sidebars.yaml ├── product-4 │ ├── intro.md │ ├── command_reference.md │ └── sidebars.yaml ├── redocly.yaml └── sidebars.yaml
sidebars.yaml
file for Product 1 that links to three Markdown pages with labels:- page: intro.md label: Introduction to Product 1 - page: install.md label: Install Product 1 - page: quickstart.md label: Quickstart guide for Product 1
- In the sidebars file in the root of your project, add page entries for the landing pages for each product. Sample
sidebars.yaml
file in the root of your project with entries for the landing pages:- page: ./product1/intro label: Product 1 doc - page: ./product2/intro.md label: Product 2 doc - page: ./product3/intro.md label: Product 3 doc - page: ./product4/intro.md label: Product 4 doc
Set sidebar
Set the sidebar of a Markdown or React page by adding a relative path to a sidebars.yaml
file in the page's front matter. This sets a page's sidebar even if that page isn't listed in the sidebars.yaml
file.
The following example uses front matter to set the sidebar on a Markdown page using front matter:
--- sidebar: ../sidebars.yaml --- # Example page
The following example uses front matter to set the sidebar on a React page using front matter:
import React from 'react'; export const frontmatter = { sidebar: '../sidebars.yaml', };
Related how-tos
- Hide the sidebar using sidebar configuration.
- Check the sidebar reference for all configuration options and more examples.
- Controlling group-level permissions using RBAC in the sidebar.