Navigation

Use docs.json to control tabs, sidebar groups, and page order. Start simple, then add structure only if you need it.

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: best default for most docs sites
• navigation.dropdowns: top-level categories; currently rendered as tabs
• navigation.groups + navigation.pages: good for a single simple section
• navigation.versions: multiple product versions — only the default version renders today; the others are reported and skipped
• 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 (title is a link; chevron toggles); others only expand/collapse

Anchors#

Anchors render as prominent links above the sidebar:

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

Anchors that contain their own pages or groups are recognized but not implemented yet.

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
• are excluded from sitemap.xml and marked noindex (unless seo.indexing is "all")

More examples#

Dropdowns#

{
  "navigation": {
    "dropdowns": [
      {
        "dropdown": "Docs",
        "pages": ["index", "configuration"]
      }
    ]
  }
}

Versions#

{
  "navigation": {
    "versions": [
      {
        "version": "v2",
        "default": true,
        "tabs": [
          {
            "tab": "Docs",
            "pages": ["index", "installation"]
          }
        ]
      }
    ]
  }
}

Languages#

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "default": true,
        "tabs": [
          {
            "tab": "Docs",
            "pages": ["index", "installation"]
          }
        ]
      }
    ]
  }
}

Common mistakes#

You will see a config error when:

• navigation is missing
• no pages are discovered
• duplicate page file slugs exist
• duplicate route slugs exist
• referenced docs files do not exist in content/docs

Slug tips#

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