Navigation

Quick start#

Use one tab with one group:

{
  "navigation": {
    "tabs": [
      {
        "tab": "Docs",
        "groups": [
          { "group": "Getting started", "pages": ["index", "installation"] }
        ]
      }
    ]
  }
}

When to use each pattern#

• navigation.tabs — the best default for most docs sites
• navigation.dropdowns — top-level categories rendered as menus
• navigation.groups + navigation.pages — good for a single simple section
• navigation.versions — multiple product versions (only the default version renders)
• navigation.languages — translated docs (same current limitation as versions)

Page entries#

Inside pages, you can mix:

String slugs — the file path without extension: "installation"

Page objects — for custom labels, icons, tags, or hidden pages:

{ "page": "installation", "title": "Install", "icon": "download", "tag": "New" }

• title (or label, which wins) — custom sidebar text
• icon — a lucide icon name shown beside the label
• tag — a short badge shown after the label
• hidden — keep the page out of the sidebar and search; it is still built and reachable by URL

External links:

{ "href": "https://github.com/example/repo", "label": "GitHub", "icon": "github" }

Nested groups — arbitrarily deep, with an optional landing page:

{
  "group": "Getting started",
  "root": "index",
  "icon": "rocket",
  "expanded": true,
  "collapsible": false,
  "pages": ["installation", "configuration"]
}

Set collapsible: false to keep a group open without a chevron. Groups also accept hidden, which hides the group and everything in it.

Collapsible groups#

Groups are collapsible and show a chevron by default. Top-level groups start expanded; nested groups start collapsed unless expanded: true is set or the current page is inside them. Navigating into a group reopens it.

The interaction.drilldown key controls what clicking a group header does:

{ "interaction": { "drilldown": true } }

• true — expanding a group also navigates to its root (or first) page
• false — the header only expands and collapses
• unset — headers with a root page navigate; others only expand/collapse

Anchors#

Anchors render as prominent links above the sidebar:

{
  "navigation": {
    "anchors": [
      { "anchor": "Community", "href": "https://discord.gg/example", "icon": "users" }
    ]
  }
}

Hidden pages#

Any tab, group, page, or link accepts hidden: true. Hidden pages are still prerendered and reachable by URL, but they do not appear in the sidebar, are skipped by prev/next paging, and are excluded from sitemap.xml.

Common mistakes#

You will see a config error when navigation is missing, no pages are discovered, duplicate page or route slugs exist, or a referenced docs file does not exist in content/docs.

Slug tips#

• .md and .mdx extensions are optional in pages entries
• the docs/ prefix is accepted and removed
• trailing /index collapses to the parent route slug
• "index" maps to the documentation home

Back to Configuration overview.