# Configure sidebars

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:

```treeview
├── index.md
├── concept-1.md
├── concept-2.md
└── concept-11.md
```

API 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.

## API description files in sidebars

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`](/docs/platform/content/api-docs/openapi-extensions/x-tag-groups).

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](/docs/platform/navigation/navigation-tabs).

Link titles in the sidebar are by default the first heading title on the page.
You can use the [`label`](#link-options) option in a `sidebars.yaml` file to change the link title.

Projects that have [multiple products](/docs/platform/navigation/multi-product) or the [catalog](/docs/platform/config/catalog-classic), 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](/docs/platform/config/sidebar) in `redocly.yaml`.

## Sidebars configuration options

Specify the order and link text for side navigation items by creating a `sidebars.yaml` file.

### Link options

| Option | Type | Description |
| --- | --- | --- |
| page | string | **CONDITIONALLY REQUIRED.** Relative or absolute path to the file (extension included), or a full route slug which represents the page to link to. **Mutually exclusive** with the `href` option. If you don't include a `label` option, the link text matches the level 1 heading of the page. **Examples**: `./index.md`, `/docs/tutorial.md`, `../../glossary.md`, `/info#admonition`, `./test.md#rename`. |
| href | string | **CONDITIONALLY REQUIRED.** URL to link to. **Mutually exclusive** with the `page` option. If you don't include the `label` option, the link text matches the value of `href`. **Examples**: `https://redocly.com`, `https://www.openapis.org/`. |
| label | string | Link text displayed for the item. |
| labelTranslationKey | string | Sets the translation key for an item's link text. Used for [localization](/docs/platform/content/localization/localize-labels#localize-user-defined-ui-elements). |
| 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`. |
| icon | string or [srcSet](#icon-object) | Either:- A [Font Awesome](https://fontawesome.com/icons) icon name.   Redocly has the following icon packs built in: Classic Regular, Classic Solid, Duotone Solid, and Classic Brands.   The icons automatically adjust their colors when users change the color mode.      To add an icon from the Classic Regular pack, you can provide the icon name only or prefix the name with `regular`.   To add an icon from another built-in pack, prefix the icon name with `solid` (Classic Solid), `duotone` (Duotone Solid), or `brands` (Classic Brands).      **Examples:** `book`, `duotone book`, `brands github`      Using other prefixes, including the `fa-` prefix, causes the icon to not render. - Relative path to an icon image file.      **Example:** `./images/config-icon.svg` - A [srcSet](#icon-object) object.   When configured, the icon changes when the user switches between color modes.      **Example:**         ```yaml   icon:     srcSet: "./images/config-icon.svg light, ./images/config-icon-dark.svg dark"   ``` |
| rbac | object | Page-level access controls for sidebar links. See [Configure RBAC in sidebar](/docs/platform/access/links-and-groups-permissions#in-the-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](/docs/platform/customization/eject-components). |
| badges | [[Badge object](#badge-object)] | List of badges to display next to the sidebar item label. Each badge has a `name` (required) and optional `color`. |

### Group options

| 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](/docs/platform/content/localization/localize-labels#localize-user-defined-ui-elements). |
| 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`. |
| icon | string or [srcSet](#icon-object) | Either:- A [Font Awesome](https://fontawesome.com/icons) icon name.   Redocly has the following icon packs built in: Classic Regular, Classic Solid, Duotone Solid, and Classic Brands.   The icons automatically adjust their colors when users change the color mode.      To add an icon from the Classic Regular pack, you can provide the icon name only or prefix the name with `regular`.   To add an icon from another built-in pack, prefix the icon name with `solid` (Classic Solid), `duotone` (Duotone Solid), or `brands` (Classic Brands).      **Examples:** `book`, `duotone book`, `brands github`      Using other prefixes, including the `fa-` prefix, causes the icon to not render. - Relative path to an icon image file.      **Example:** `./images/config-icon.svg` - A [srcSet](#icon-object) object.   When configured, the icon changes when the user switches between color modes.      **Example:**         ```yaml   icon:     srcSet: "./images/config-icon.svg light, ./images/config-icon-dark.svg dark"   ``` |
| badges | [[Badge object](#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](#link-options)) | **REQUIRED.** A list of items, configured using [link options](#link-options). |

### Separator options

| Option | Type | Description |
| --- | --- | --- |
| separator | string | Static text that separates items on the sidebar. |
| icon | string or [srcSet](#icon-object) | Either:- A [Font Awesome](https://fontawesome.com/icons) icon name.   Redocly has the following icon packs built in: Classic Regular, Classic Solid, Duotone Solid, and Classic Brands.   The icons automatically adjust their colors when users change the color mode.      To add an icon from the Classic Regular pack, you can provide the icon name only or prefix the name with `regular`.   To add an icon from another built-in pack, prefix the icon name with `solid` (Classic Solid), `duotone` (Duotone Solid), or `brands` (Classic Brands).      **Examples:** `book`, `duotone book`, `brands github`      Using other prefixes, including the `fa-` prefix, causes the icon to not render. - Relative path to an icon image file.      **Example:** `./images/config-icon.svg` - A [srcSet](#icon-object) object.   When configured, the icon changes when the user switches between color modes.      **Example:**         ```yaml   icon:     srcSet: "./images/config-icon.svg light, ./images/config-icon-dark.svg dark"   ``` |
| 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. |

### Tab options

Use `tab` entries as the top-level entries of a `sidebars.yaml` file to split it into [navigation tabs](/docs/platform/navigation/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](/docs/platform/navigation/sidebars#sidebars-configuration-options)] | 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](/docs/platform/navigation/navigation-tabs#menu-entry-options)] | 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](/docs/platform/navigation/sidebars#icon-object) | Icon displayed next to the tab label. Accepts a [Font Awesome](https://fontawesome.com/icons) icon name or a relative path to an icon image file. |
| tabTranslationKey | string | Sets the translation key for the tab label. Used for [localization](/docs/platform/content/localization/localize-labels#localize-user-defined-ui-elements). |
| rbac | object | Access controls for the tab. See [Configure RBAC in sidebar](/docs/platform/access/links-and-groups-permissions#in-the-sidebar) for more information. |

### Menu entry options

A menu entry accepts the same options as a [sidebar link](/docs/platform/navigation/sidebars#link-options), 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](/docs/platform/navigation/sidebars#sidebars-configuration-options)] | Sidebar displayed while the entry is active. Accepts links, groups, separators, directories, and `$ref` to other sidebar files. |
| icon | string or [srcSet](/docs/platform/navigation/sidebars#icon-object) | Icon displayed next to the entry label. Accepts a [Font Awesome](https://fontawesome.com/icons) icon name or a relative path to an icon image file. |
| labelTranslationKey | string | Sets the translation key for the entry label. Used for [localization](/docs/platform/content/localization/localize-labels#localize-user-defined-ui-elements). |
| rbac | object | Access controls for the entry. See [Configure RBAC in sidebar](/docs/platform/access/links-and-groups-permissions#in-the-sidebar) for more information. |

### Badge object

| 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:** `red`, `green`, `blue`, `grey`, `turquoise`, `magenta`, `purple`, `carrot`, `raspberry`, `orange`, `grass`, `persian-green`, `sky`, `blueberry`.  **Supported status colors:** `success`, `processing`, `error`, `warning`, `default`, `approved`, `declined`, `pending`, `active`, `draft`, `deprecated`, `product`.  Default: `grey`. |
| 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](https://fontawesome.com/icons) icon name or a relative path to an icon image file. |

### Icon object

| 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. |

## Examples

### Basic sidebar structure

The following example shows a simple `sidebars.yaml` file with pages and basic groups:

```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 API
```

### Groups with landing pages

Groups can navigate to a landing page when clicked by adding a `page` property:

```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 API
```

### Nested groups and expand behavior

Groups can contain other groups and have customizable expand behavior:

```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.md
```

### Separators and organization

Use separators to organize sidebar content into distinct sections:

```yaml
- 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
```

### Complete sidebar configuration

The following example shows a comprehensive `sidebars.yaml` file with various options:

```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
- 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
```

### Additional properties

Use `additionalProps` to add custom data to sidebar items:

```yaml
- 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.

### Badges

Use `badges` to add visual indicators to sidebar items:

```yaml
- 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)
```

## Resources

- **[Navigation tabs](/docs/platform/navigation/navigation-tabs)** - Add a second row of navigation that splits a sidebar into sections
- **[Build navigation](/docs/platform/navigation)** - Overview of all navigation components and patterns for creating comprehensive site navigation structures
- **[Navbar configuration](/docs/platform/config/navbar)** - Configure the navbar navigation with links
- **[Footer configuration](/docs/platform/config/footer)** - Configure the footer navigation with links, copyright information, and organizational elements
- **[Front matter configuration options](/docs/platform/config/front-matter-config)** - Use front matter add a sidebar on individual pages for custom page layouts