Navigation tabs split a large site into sections, such as guides, API reference, and changelog. Each tab appears in a row under the navbar and has its own sidebar. Readers switch sections with one click, and the sidebar lists only the pages of the current section.
Define navigation tabs as the top-level entries of a sidebars.yaml file. Each tab either opens a landing page and shows a sidebar from its items, or opens a dropdown menu of pages.
The following example organizes product documentation into three tabs:
- tab: Guides
page: guides/index.md
icon: book
items:
- page: guides/quickstart.md
- group: Integrate
items:
- page: guides/authentication.md
- page: guides/webhooks.md
- group: Tutorials
directory: guides/tutorials
- tab: API reference
icon: code
menu:
- page: apis/payments.yaml
label: Payments API
- page: apis/accounts.yaml
label: Accounts API
items:
- page: apis/accounts/migrate-to-v2.md
- page: apis/events/index.md
label: Webhook events
items:
- page: apis/events/retries.md
- tab: Changelog
page: changelog.md
In this example:
- Guides opens
guides/index.md, and the sidebar displays the quickstart and the Integrate and Tutorials groups. - API reference opens a dropdown with three entries. The two API entries display the generated API navigation in the sidebar, and Accounts API adds a migration guide after it. Webhook events is a Markdown page with its own sidebar.
- Changelog opens a single page and has no sidebar items.
| 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. |
The tab row appears under the navbar on screens 960px and wider. A tab with a menu opens a dropdown of its entries.
On mobile devices, the mobile menu shows the tabs in a dropdown above the sidebar of the current tab.
The tab that contains the current page stays highlighted while readers move between its pages. The sidebar displays only the items listed in that tab, or the items of the active menu entry.
When a tab or menu entry opens an API description, the page displays the API reference. The sidebar lists the navigation generated from the description, followed by any items you add.
The build fails if a sidebars.yaml file breaks one of these rules:
- All top-level entries are tabs, or none are. To display a plain link or group, put it in a tab's
items. Every versioned copy of a sidebar also uses tabs, or none of them do. - A page belongs to one tab only. If two tabs or two menu entries list the same page, the error message names both.
- Tabs don't nest. A tab can't contain another tab, and
menuworks only directly on a tab. This rule also applies to sidebar files included with$ref. - A tab has
pageormenu, not both. A tab withmenucan't haveitems, and every menu entry needs apage. Putdirectory,group,href, and$refentries initems, not on the tab itself. - Tab and menu entry pages don't accept anchors. Set
pageto a file path such asguides/index.md, notguides/index.md#setup. Links in a tab'sitemscan still use anchors.
- Configure sidebars - Configure the links, groups, and referenced sidebar files that go into a tab's
items - Build navigation - Overview of navigation areas and how they work together
- Component CSS variables - Full list of variables that style the navigation tabs row
- Version content - Organize versioned folders and their sidebars