Last updated

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.

To customize the order and link titles of your sidebar:

  1. Create a sidebars.yaml file and add it to the root of your project.
  2. Add the page option with the value of the file path or the href 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 page intro.md with the first heading on that page as link text and a link to http://example.com with the URL as the link text:
    - page: intro.md
- href: http://example.com
  3. (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 the page option, or the value for the href 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 is false by default. For example, the following configuration adds a sidebar with a link to the Markdown page intro.md with "Introduction" link text and sidebar.intro translation key, and a link to the Markdown page quickstart.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:

  1. Create a sidebars.yaml file and add it to the root of your project.
  2. 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
  3. 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
  4. In sidebars.yaml, add an entry with $ref to point to the topic-sidebars.yaml file (including the directory path if applicable):
    - $ref: ./topic-sidebars.yaml
  5. 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:

  1. 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
  2. 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
  3. In the folder for each product, add a sidebars file. A sample file structure:
     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
    Sample 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
  4. 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-example.md
---
sidebar: ../sidebars.yaml
---

# Example page

The following example uses front matter to set the sidebar on a React page using front matter:

sidebar-example.page.tsx
import React from 'react';

export const frontmatter = {
  sidebar: '../sidebars.yaml',
};
 
Next page