Sidebars configuration options

If you want to specify the order and link text for the items in your side navigation, create a sidebars.yaml file.

Requirements

Version > 0.1.0

Link options

Option	Type	Description
page	string	CONDITIONALLY REQUIRED.* Path to the file (extension included) that represents the page to link to. If no `label` is provided, the link text will match the page's level 1 heading.
href	string	CONDITIONALLY REQUIRED.* URL to link to. Works with absolute and relative URLs. If no `label` is provided, the link text will match the value used for href.
label	string	Link text displayed for the item.
labelTranslationKey	string	Sets the translation key for an item's link text. Used for localization.
external	boolean	Configures item to open in new tab and adds an external link symbol next to sidebar entry. Defaults to `false`. Does not apply to paths to version subfolders.
disconnect	boolean	Used with `page` option to include links to items in the sidebar without assigning the sidebar to that page. Defaults to `false`.
icon	string	Path to icon image file. Shown on left side of sidebar entry.
rbac	object	Page-level access controls for sidebar links. See Configure RBAC in sidebar for more information.

* Sidebar links must use either the page or href option ("mutually exclusive").

Group options

Option	Type	Description
group	string	REQUIRED. Name of the group.
page	string	Path to the file (and extension) that represents a page. Loads when the group is clicked.
directory	string	Path to a folder. Files in the folder are automatically added to the sidebar.
groupTranslationKey	string	Sets the translation key for a group. Used for localization.
menuStyle	string	Values: `drilldown` -- when user selects a group, the sidebar shows only that group's items and hides the other sidebar elements.
expanded	string	Values: `true` -- Items are expanded when page loads. Users can click to collapse the group. `false` -- Default. Items are collapsed when page loads. Users can click to expand. `always` -- Items are expanded when page loads and can't be collapsed.
selectFirstItemOnExpand	boolean	Automatically open first item in group when group is clicked and expanded. Defaults to `false`.
icon	string	Path to icon image file. Shown on left side of group.
items	object (Link)	REQUIRED. A list of items, where each item is configured using link options.

Additional options

Option	Type	Description
separator	string	Static text used to separate items on the sidebar.
separatorLine	boolean	Horizontal bar used to break sidebar into sections. Can be used in sidebar root or inside a group.
$ref	string	Path to another sidebar file. Entries from other sidebar are expanded into the sidebar created by this `sidebars.yaml` file. See Compose a single sidebar from multiple `sidebars.yaml` files for more details.

Example

The following is an example sidebars.yaml file:

sidebars.yaml

- page: overview.md
- page: installation.md
  label: Installation
- group: Config
  selectFirstItemOnExpand: true
  items:
    - page: config/index.md
    - page: config/developer-onboarding.md
      label: Developer Onboarding
    - group: Reference
      page: config/reference/index.md
      items:
        page: config/reference/config-files.md
        label: Config Files
- group: Content
  menuStyle: drilldown
  icon: ./images/custom-icon.png
  items:
    - directory: content
- $ref: ./templates/sidebars.yaml
- group: Plugins
  items:
    - directory: plugins
- group: Resources
  items:
    - href: https://redocly.com/docs
      label: Great docs
    - href: /docs/cli/v1.3
      label: Legacy CLI docs