Sidebar navigation

Define what to show in the left navigation pane in the sidebars.yaml file.

If a page is listed within a sidebar, the corresponding sidebar will display on the page. If a page does not have any corresponding sidebar, it will be displayed without a sidebar.

A page should only be listed in one sidebar.

NOTE: While there is support for multiple sidebar navigation schemes, it is most common to use one.

Below is a sample sidebars.yaml file contents.

gettingStarted:
  - group: Get Started
    expanded: true
    pages:
      - label: Overview ✅
        page: developer-portal/overview.md
      - separator: true
      - label: Top Nav
        page: developer-portal/top-navigation.md
      - label: Footer Nav
        page: developer-portal/footer-navigation.md
      - label: Sidebar Nav
        page: developer-portal/sidebar-nav.md
  - group: Data Exports Guide
    expanded: false
    pages:
      - group: Nested Group
        expanded: false
        pages:
          - separator: Another Separator
      - label: Quickstart
        page: developer-portal/quickstart.md
      - separator: Separator Example
      - label: Using Arguments
        page: developer-portal/arguments.md
      - label: Using Date Ranges
        page: developer-portal/date-range.md
      - separator: true
      - page: reference.page.yaml
anotherSidebar:
  - label: Sample

The gettingStarted is a key name and is not utilized by the web app for display purposes. If you decide to have multiple sidebars, then you'll need to use a different key name for each of them. In the example above, we added another key anotherSidebar.

The sidebars can then be composed of pages, separators, and groups.

Sidebar components

Groups

The groups can be composed of pages, labels, separators, and other (nested) groups.

A group can be expanded with a few possible configurations:

Use groups to organize pages and nested groups. While there are no theoretical limits on nesting, there are practical limits to keep the documentation easy to navigate for the users. The sample below shows two groups nested:

  - group: Data Exports Guide
    expanded: false
    pages:
      - group: Nested Group
        expanded: false
        pages:
          - separator: Another Separator

Separators

A separator can have a string value and is represented in the left navigation pane with a slightly different style.

Labels

A label is a property that can optionally be used in conjunction with a page definition. By default, if a label is not specified in the sidebars.yaml file, the app will use the title from the corresponding page.

Pages

A page is a relative path to a file. Typically, it is a markdown or MDX file. However, to reference an OpenAPI definition, it may be a path to a YAML file.

Include your API reference in the sidebar

Redocly Portal provides the possibility to include the entire API reference (or parts of it) in the left navigation pane.

There are multiple options for doing that.

Here is a simple reference to a YAML file defined like this in the sidebars:

      - page: reference.page.yaml

And this is what the reference.page.yaml file is composed of itself:

type: redoc
definitionId: petstore
tags: ['pet', 'user']
showInfo: true
expand: true

The configuration of that YAML file influences how data is presented into the left sidebar navigation. For details, see Integrating API reference.