# 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.***
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](/docs/realm/content/localization/localize-labels#localize-base-ui-components). |
| 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](https://fontawesome.com/icons) 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](/docs/realm/access/links-and-groups-permissions#in-the-sidebar) for more information. |


* Sidebar links must use either the `page` or `href` option ("mutually exclusive").

## 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/realm/content/localization/localize-labels#localize-base-ui-components). |
| 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](https://fontawesome.com/icons) 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](#link-options)) | **REQUIRED.**
A list of items, configured using [link options](#link-options). |


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


## Examples

### Basic sidebar structure

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


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

### Groups with landing pages

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


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

### Nested groups and expand behavior

Groups can contain other groups and have customizable expand behavior:


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

### Separators and organization

Use separators to organize sidebar content into distinct sections:


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

### Complete sidebar configuration

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


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