Define what to show in the left navigation pane in the
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
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
The sidebars can then be composed of pages, separators, and groups.
The groups can be composed of pages, labels, separators, and other (nested) groups.
A group can be expanded with a few possible configurations:
||The pages will be open (expanded) when the page loads.|
||The pages will be collapsed when the page loads.|
||The pages will be open (expanded) and cannot be collapsed.|
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
A separator can have a string value and is represented in the left navigation pane with a slightly different style.
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.
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.
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.