Tabs

When a docs site grows past a single sidebar, readers need a way to switch between major areas (guides, feature catalog, component reference) without scrolling one combined navigation tree.

Site tabs are primary navigation in the site header. You define them in the tabs array in docs.json. Each tab has an id, a display title, and an href that points to that section's landing path.

The sidebar is still one configuration tree. You scope groups to a tab with the optional tab field on each sidebar group. While a tab is active, docs.page shows groups tagged for that tab, plus any groups with no tab value (shared across every tab).

That is different from the <Tabs> MDX component, which creates switchable panels inside a page. Site tabs split the header and sidebar (tab labels in the header and matching sidebar groups), not inline content.

See Sidebar for how groups and pages are structured inside each tab's sidebar.

Add a tabs array at the top level of docs.json. Each entry needs a stable id, a reader-facing title, and an href for the section root:

{
  "tabs": [
    { "id": "docs", "title": "Documentation", "href": "/" },
    { "id": "features", "title": "Features", "href": "/features" },
    { "id": "components", "title": "Components", "href": "/components" },
    { "id": "reference", "title": "Reference", "href": "/reference" }
  ]
}

When tabs is non-empty, docs.page renders those labels in the header below the logo row. Clicking a tab navigates to its href. With no tabs array (or an empty one), that tab row is omitted and the full sidebar is always visible.

For every field on tabs entries, including optional locale, see docs.json.

Tag sidebar groups with the tab field set to a tab id:

{
  "sidebar": [
    {
      "group": "Getting Started",
      "tab": "docs",
      "pages": [{ "title": "Introduction", "href": "/" }]
    },
    {
      "group": "Publish",
      "tab": "features",
      "pages": [{ "title": "Public GitHub hosting", "href": "/features/public-github-hosting" }]
    },
    {
      "group": "Reference",
      "tab": "reference",
      "pages": [{ "title": "docs.json", "href": "/reference/docs-json" }]
    }
  ]
}

While the Features tab is active, only groups where tab is "features" appear in the sidebar, along with any group that omits tab. Omit tab when a group should appear regardless of which header tab is selected, for example, a persistent link block or a cross-cutting section.

You maintain one sidebar array (or one locale-keyed object when using multi-locale navigation). Tab scoping is a filter at render time, not a separate sidebar tree per tab.

Each tab entry may include an optional locale field. On a locale-free URL, docs.page shows only tabs with no locale set. On a localized URL such as /fr/installation, only tabs whose locale matches the active locale appear.

Use this when header sections differ by language, for example, a tab that only applies to the French navigation set. Most single-language sites leave locale off every tab.