URL: /guides/authoring/navigation

---
title: Navigation
description: How to structure tabs, groups, anchors, and dropdowns in docs.json.
icon: "list-tree"
---

# 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`:

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

Groups bundle pages under a heading:

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

Tabs split the navigation into top-level sections:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```bash
bun x tangly check --strict
```

Orphan list appears in the report.