Specify the order and link text for side navigation items by creating a sidebars.yaml file.
| Option | Type | Description |
|---|---|---|
| page | string | CONDITIONALLY REQUIRED.* Path to the file (extension included) that links to a page. If no label is provided, the link text matches the page's level 1 heading. Use an absolute or relative path. For external links, use href instead. Examples: ./index.md, /docs/tutorial.md, ../../glossary.md. |
| href | string | CONDITIONALLY REQUIRED.* URL to link to. Works with absolute and relative URLs. If no label is provided, the link text matches the href value. The link checker does not follow href links. Use a URL, not a page path (✅ https://redocly.com; ❌ ./index.md). |
| 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 | Opens item in a new tab and adds an external link symbol. Defaults to false. Does not apply to paths to version subfolders. |
| disconnect | boolean | Includes links in the sidebar without assigning the sidebar to that page. Defaults to false. |
| icon | string | A Font Awesome or relative path to icon image file. Appears on left side of sidebar entry. Font Awesome icons can be prefixed with type: duotone, solid, regular or brands. Example: book, duotone book, brands github, ./images/config-icon.svg. |
| 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").
| Option | Type | Description |
|---|---|---|
| group | string | REQUIRED. Name of the group. |
| page | string | Path to the file that loads when the group is clicked. |
| directory | string | Path to a folder. Files in the folder automatically appear in the sidebar and are sorted in the natural order. |
| groupTranslationKey | string | Sets the translation key for a group. Used for localization. |
| menuStyle | string | Values:drilldown -- Shows only the selected group's items and hides other sidebar elements. |
| expanded | string | Values:true -- Items are expanded when page loads. Users can collapse the group.false -- Default. Items are collapsed when page loads. Users can expand.always -- Items are expanded when page loads and cannot be collapsed. |
| selectFirstItemOnExpand | boolean | Opens the first item in a group when the group is expanded. Defaults to false. |
| icon | string | A Font Awesome or relative path to icon image file. Appears on left side of group. Font Awesome icons can be prefixed with type: duotone, solid, regular or brands. Example: book, duotone book, brands github, ./images/config-icon.svg. |
| items | object (Link) | REQUIRED. A list of items, configured using link options. |
| Option | Type | Description |
|---|---|---|
| separator | string | Static text that separates items on the sidebar. |
| separatorLine | boolean | Horizontal bar that breaks the sidebar into sections. Works in sidebar root or inside a group. |
| $ref | string | Path to another sidebar file. Entries from the referenced sidebar expand into this sidebar. |
The following example shows a simple sidebars.yaml file with pages and basic groups:
sidebars.yaml
- page: overview.md
- page: installation.md
label: Installation
- group: Getting started
items:
- page: quickstart.md
- page: tutorials/first-steps.md
label: First steps
- group: API reference
items:
- page: users-api.yaml
label: Users API
- page: orders-api.yaml
label: Orders APIGroups can navigate to a landing page when clicked by adding a page property:
sidebars.yaml
- page: overview.md
- group: User guides
page: guides/index.md
selectFirstItemOnExpand: true
items:
- page: guides/getting-started.md
label: Getting started
- page: guides/advanced.md
label: Advanced usage
- group: API reference
page: api/index.md
items:
- page: api/users.yaml
label: Users API
- page: api/orders.yaml
label: Orders APIGroups can contain other groups and have customizable expand behavior:
sidebars.yaml
- page: overview.md
- group: Documentation
expanded: true
items:
- page: docs/getting-started.md
- group: Guides
expanded: false
items:
- page: guides/authentication.md
- page: guides/rate-limiting.md
- group: Advanced topics
expanded: always
items:
- page: advanced/webhooks.md
- page: advanced/custom-domains.mdUse separators to organize sidebar content into distinct sections:
sidebars.yaml
- group: User documentation
items:
- separator: Getting started
- page: quickstart.md
- page: installation.md
- separator: Advanced features
- page: advanced/webhooks.md
- page: advanced/integrations.md
- separatorLine: true
- separator: API reference
- page: api/users.yaml
- page: api/orders.yamlThe following example shows a comprehensive sidebars.yaml file with various options:
sidebars.yaml
- page: overview.md
- page: installation.md
label: Installation
- group: Configuration
icon: duotone cog
selectFirstItemOnExpand: true
expanded: true
items:
- page: config/index.md
- page: config/developer-onboarding.md
label: Developer onboarding
- group: Reference
page: config/reference/index.md
separatorLine: true
items:
- page: config/reference/config-files.md
label: Config files
- group: Content
menuStyle: drilldown
icon: ./images/content-icon.png
items:
- directory: content
- $ref: ./templates/sidebars.yaml
- group: Plugins
items:
- directory: plugins
- group: Resources
separatorLine: true
items:
- href: https://redocly.com/docs
label: Documentation
external: true
- href: /docs/cli/v1.3
label: Legacy CLI docs