The sidebar is generated automatically based on your project's file structure if no sidebars.yaml file exists. By default, items in the sidebar menu are sorted using natural ordering. Letter characters follow the alphabetical order and multi-digit numbers are treated as a single character. index.md files by default appear as the first item in any sidebar.
For example, the following files: index.md, concept-1.md, concept-11.md, and concept-2.md, result in the following sidebar:
├──index.md├──concept-1.md├──concept-2.md└──concept-11.mdAPI description files automatically add items to the sidebars. These items are generated according to the internal structure of the tags and endpoints described in the file and preserve the order of this structure.
Adding an OpenAPI file to sidebars.yaml only controls where the entry point to that API appears in the site-wide sidebar. The internal structure of the API—its groups, tags, and endpoints—is automatically derived from the OpenAPI specification itself and cannot be modified using sidebars.yaml options. To customize the internal organization of your API, use OpenAPI extensions like x-tagGroups.
You can customize the sidebar by adding a sidebars.yaml file to the root of your project. A sidebars.yaml file must include all files or directories you want to have in a sidebar: new files and directories aren't added automatically.
To split a large site into sections with their own sidebars, see Navigation tabs.
Link titles in the sidebar are by default the first heading title on the page. You can use the label option in a sidebars.yaml file to change the link title.
Projects that have multiple products or the catalog, generate separate sidebars for each of item.
In complex projects, you can add separate sidebars.yaml files for each section of your project. Either add the files in project folders, or in the root folder with prefixes. For example: installation.sidebars.yaml, config.sidebars.yaml. Then reference these files in the sidebars.yaml at the root of your project.
To hide the sidebar for your entire project, use the sidebar option in redocly.yaml.
Specify the order and link text for side navigation items by creating a sidebars.yaml file.
| Option | Type | Description |
|---|---|---|
| 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. Default: false. Does not apply to paths to version subfolders. |
| disconnect | boolean | Includes links in the sidebar without assigning the sidebar to that page. Default: false. |
| rbac | object | Page-level access controls for sidebar links. See Configure RBAC in sidebar for more information. |
| additionalProps | object | Additional properties for the sidebar item. Pass arbitrary data that can be accessed in custom theme components. To learn how to customize theme components, see: Eject components. |
| badges | [Badge object] | List of badges to display next to the sidebar item label. Each badge has a name (required) and optional color. |
| 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 - Displays 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 - Items are collapsed when page loads. Users can expand. always - Items are expanded when page loads and cannot be collapsed. Default: false. |
| selectFirstItemOnExpand | boolean | Opens the first item in a group when the group is expanded. Defaults to false. |
| badges | [Badge object] | List of badges to display next to the sidebar item label. Each badge has a name (required) and optional color. |
| items | object (Link options) | 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. |
Use tab entries as the top-level entries of a sidebars.yaml file to split it into navigation tabs. When one top-level entry is a tab, all top-level entries must be tabs.
| Option | Type | Description |
|---|---|---|
| tab | string | REQUIRED. Label displayed in the tab row. |
| page | string | Path to the tab's landing page. The page can be a Markdown file or an OpenAPI, AsyncAPI, or GraphQL description. Mutually exclusive with menu. |
| items | [Sidebar item] | Sidebar displayed while the tab is active. Accepts links, groups, separators, directories, and $ref to other sidebar files. Use together with page. |
| menu | [Menu entry] | Dropdown of pages for the tab. Each entry opens its own page and displays its own sidebar. Mutually exclusive with page and items. |
| icon | string or srcSet | Icon displayed next to the tab label. Accepts a Font Awesome icon name or a relative path to an icon image file. |
| tabTranslationKey | string | Sets the translation key for the tab label. Used for localization. |
| rbac | object | Access controls for the tab. See Configure RBAC in sidebar for more information. |
A menu entry accepts the same options as a sidebar link, plus items. The most common options are:
| Option | Type | Description |
|---|---|---|
| page | string | REQUIRED. Path to the page the entry opens. The page can be a Markdown file or an OpenAPI, AsyncAPI, or GraphQL description. |
| label | string | Link text displayed in the dropdown. Default: the title of the page. |
| items | [Sidebar item] | Sidebar displayed while the entry is active. Accepts links, groups, separators, directories, and $ref to other sidebar files. |
| icon | string or srcSet | Icon displayed next to the entry label. Accepts a Font Awesome icon name or a relative path to an icon image file. |
| labelTranslationKey | string | Sets the translation key for the entry label. Used for localization. |
| rbac | object | Access controls for the entry. See Configure RBAC in sidebar for more information. |
| Option | Type | Description |
|---|---|---|
| name | string | REQUIRED. The text that displays in the badge. |
color | string | The color of the badge. Supports predefined color names for consistent styling or direct color values for custom backgrounds. Supported color names: Supported status colors: Default: |
| position | string | The position of the badge relative to the label text. Possible values: before, after. Default: after. |
| icon | string | Icon to display inside the badge. Accepts a Font Awesome icon name or a relative path to an icon image file. |
| Option | Type | Description |
|---|---|---|
| srcSet | string | Comma-separated list of icon file paths and corresponding color modes. When configured, the icon changes when the user switches between color modes. |
The following example shows a simple sidebars.yaml file with pages and basic groups:
- 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 API
Groups can navigate to a landing page when clicked by adding a page property:
- 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 API
Groups can contain other groups and have customizable expand behavior:
- 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.md
Use separators to organize sidebar content into distinct sections:
- group: User documentation
items:
- separator: Getting started
icon: book
- 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.yaml
The following example shows a comprehensive sidebars.yaml file with various options:
- 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
- page: /setup-links#config
- group: Resources
separatorLine: true
items:
- href: https://redocly.com/docs
label: Documentation
external: true
- href: /docs/cli/v1.3
label: Legacy CLI docs
Use additionalProps to add custom data to sidebar items:
- page: overview.md
label: Overview
additionalProps:
difficulty: beginner
- group: Getting started
items:
- page: quickstart.md
label: Quick Start
additionalProps:
estimatedTime: 5 minutes
- page: installation.md
label: Installation
additionalProps:
difficulty: beginner
Custom theme components can access these properties to display additional information or implement custom behavior.
Use badges to add visual indicators to sidebar items:
- page: overview.md
label: Overview
- page: new-feature.md
label: New Feature
badges:
- name: New
color: green
icon: solid star
- page: experimental-api.md
label: Experimental API
badges:
- name: Beta
color: '#ff9800'
position: before
- name: Unstable
color: var(--color-danger-base)
- group: Deprecated APIs
items:
- page: legacy-api.md
label: Legacy API
badges:
- name: Deprecated
color: var(--color-warning-base)
- Navigation tabs - Add a second row of navigation that splits a sidebar into sections
- Build navigation - Overview of all navigation components and patterns for creating comprehensive site navigation structures
- Navbar configuration - Configure the navbar navigation with links
- Footer configuration - Configure the footer navigation with links, copyright information, and organizational elements
- Front matter configuration options - Use front matter add a sidebar on individual pages for custom page layouts