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:
Setting | Description |
---|---|
expanded: true |
The pages will be open (expanded) when the page loads. |
expanded: false |
The pages will be collapsed when the page loads. |
expanded: always |
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
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.