Navigation

The navigation field in docs.json is the source of truth for your sidebar and top-bar. Pages on disk that aren’t referenced are routable but hidden from sidebars (matching Mintlify).

Pages, groups, tabs

A page is just a slug — a path without .mdx:

{ "navigation": { "pages": ["introduction", "guides/setup"] } }

Groups bundle pages under a heading:

{
  "navigation": {
    "groups": [{ "group": "Get Started", "pages": ["introduction", "quickstart"] }]
  }
}

Tabs split the navigation into top-level sections:

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [{ "group": "Get Started", "pages": ["introduction"] }]
      },
      {
        "tab": "API Reference",
        "openapi": "/openapi.json"
      }
    ]
  }
}

Anchors and dropdowns

Anchors are top-bar links — usually GitHub or external website:

{
  "navigation": {
    "global": {
      "anchors": [{ "anchor": "GitHub", "href": "https://github.com/me/proj", "icon": "github" }]
    }
  }
}

Dropdowns nest pages or external links under a single button.

Nested groups

Groups can nest. Pages inside nested groups inherit the parent’s behavior:

{
  "groups": [
    {
      "group": "Reference",
      "pages": [
        "reference/intro",
        {
          "group": "API",
          "pages": ["reference/api/overview", "reference/api/auth"]
        }
      ]
    }
  ]
}

Versions and languages

The schema accepts versions and languages arrays. Routing for them is on the roadmap and not wired today — declarations are preserved on the manifest for forward compatibility.

Pages on disk vs in nav

A .mdx file at <root>/<slug>.mdx is always routable at /<slug> — even if it’s not in nav. Use this for unlisted pages (e.g. landing pages linked from external campaigns).

To find orphans:

bun x tangly check --strict

Orphan list appears in the report.