> ## Documentation Index
> [HTML page](https://blode.md/docs/configuration/navigation)
> [Documentation index](https://blode.md/docs/llms.txt)
> Use the index to discover all available pages before exploring further.

# Navigation

Configure sidebar groups, tabs, nested pages, hidden routes, and page ordering in docs.json to control how readers browse your documentation site.

You control the sidebar hierarchy, tabbed sections, and hidden pages through the `navigation` object in `docs.json`. This page covers every navigation feature.

## Groups

Groups organize pages into collapsible sidebar sections. Each group has a label and a list of page slugs.

```json title="docs.json"
{
  "navigation": {
    "groups": [
      {
        "group": "Getting started",
        "pages": ["index", "quickstart"]
      },
      {
        "group": "Guides",
        "pages": ["guides/authentication", "guides/deployment"]
      }
    ]
  }
}
```

- `group` (type: string): Display label for the sidebar section.
- `pages` (type: string[]): Array of page slugs. Each slug maps to an MDX file relative to your docs root.
- `expanded` (type: boolean): Whether the group is expanded by default. Defaults to `true` for the first group.
- `hidden` (type: boolean): Hide this group from the sidebar while keeping its pages accessible by URL.

### Directory paths

Page slugs map directly to file paths. A slug like `domains/custom-domains` resolves to `domains/custom-domains.mdx` in your docs directory.

```
docs/
  domains/
    custom-domains.mdx   -> slug: "domains/custom-domains"
    ssl.mdx              -> slug: "domains/ssl"
  index.mdx              -> slug: "index"
```

## Tabs

Tabs add top-level sections to your documentation. Each tab contains its own set of groups, creating separate sidebar navigations.

```json title="docs.json"
{
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "groups": [
          { "group": "Getting started", "pages": ["index", "quickstart"] }
        ]
      },
      {
        "tab": "API reference",
        "groups": [
          { "group": "Endpoints", "pages": ["api/users", "api/projects"] }
        ]
      },
      {
        "tab": "Changelog",
        "href": "/changelog"
      }
    ]
  }
}
```

- `tab` (type: string, required: true): Display label for the tab. This is the `label` field in the schema.
- `groups` (type: Array<Group>): Array of sidebar groups displayed when this tab is active.
- `pages` (type: string[]): Flat list of page slugs (alternative to groups for simple tabs).
- `href` (type: string): External URL. When set, clicking the tab navigates away instead of showing a sidebar.
- `icon` (type: string): Icon name displayed next to the tab label.

> [!INFO]
> A tab must define at least one of `groups`, `pages`, or `href`.

## Hidden pages

Use the `hidden` array to keep pages accessible by URL without showing them in the sidebar. This is useful for deprecated pages, redirects, or unlisted content.

```json title="docs.json"
{
  "navigation": {
    "hidden": ["internal/debug", "legacy/old-api"],
    "groups": [{ "group": "Guides", "pages": ["index", "quickstart"] }]
  }
}
```

## OpenAPI auto-generated pages

You can generate API reference pages directly from an OpenAPI spec by adding an `openapi` field to a group instead of listing pages manually.

```json title="String source"
{
  "group": "API reference",
  "openapi": "openapi.yaml"
}
```

```json title="Object source"
{
  "group": "API reference",
  "openapi": {
    "source": "openapi.yaml",
    "basePath": "/api",
    "directory": "api-ref",
    "include": ["GET /users", "POST /users"]
  }
}
```

- `source` (type: string, required: true): Path to your OpenAPI spec file.
- `basePath` (type: string): Base path prefix for generated page slugs.
- `directory` (type: string): Output directory for generated MDX files.
- `include` (type: string[]): Filter to specific operations (e.g., `GET /users`).

## Splitting navigation with $ref

For large projects, you can split your navigation into separate JSON files using `$ref`. This keeps your main `docs.json` manageable.

```json title="docs.json"
{
  "navigation": {
    "tabs": [{ "$ref": "./nav/guides.json" }, { "$ref": "./nav/api.json" }]
  }
}
```

```json title="nav/guides.json"
{
  "tab": "Guides",
  "groups": [{ "group": "Getting started", "pages": ["index", "quickstart"] }]
}
```

## Versions

Version dropdowns let you maintain multiple documentation versions from a single project.

```json title="docs.json"
{
  "navigation": {
    "versions": [
      { "label": "v2.0", "url": "/v2" },
      { "label": "v1.0", "url": "/v1" }
    ],
    "groups": [...]
  }
}
```

- `label` (type: string, required: true): Version label displayed in the dropdown.
- `url` (type: string, required: true): URL path or full URL for this version.

## Languages

Language selectors let you link to translated versions of your documentation.

```json title="docs.json"
{
  "navigation": {
    "languages": [
      { "label": "English", "url": "/en" },
      { "label": "Japanese", "url": "/ja", "locale": "ja" }
    ],
    "groups": [...]
  }
}
```

- `label` (type: string, required: true): Language name displayed in the selector.
- `url` (type: string, required: true): URL path or full URL for this language.
- `locale` (type: string): BCP 47 locale code (e.g., `ja`, `fr`, `zh-CN`).

## Global anchors

Global anchors appear as persistent links in the navigation, visible across all tabs. Use them for external resources like your dashboard, community, or changelog.

```json title="docs.json"
{
  "navigation": {
    "global": {
      "anchors": [
        { "label": "Community", "href": "/community" },
        { "label": "Dashboard", "href": "/app" }
      ],
      "links": [
        { "label": "Blog", "href": "/blog" }
      ]
    },
    "groups": [...]
  }
}
```

- `global.anchors` (type: Array<{ label: string, href: string }>): Persistent anchor links shown across all tabs.
- `global.links` (type: Array<{ label: string, href: string }>): Additional navigation links shown globally.

## Complete navigation schema

The full navigation object supports all of the following fields:

- `tabs` (type: Array<Tab>): Top-level tabbed sections. Each tab has its own sidebar.
- `groups` (type: Array<Group>): Sidebar groups when not using tabs.
- `pages` (type: string[]): Flat list of page slugs (simplest form, no grouping).
- `hidden` (type: string[]): Page slugs accessible by URL but not shown in the sidebar.
- `versions` (type: Array<{ label, url }>): Version dropdown entries.
- `languages` (type: Array<{ label, url, locale? }>): Language selector entries.
- `global` (type: { anchors?, links? }): Global anchors and links visible across all tabs.

> [!INFO]
> Your navigation must define at least one of `groups`, `pages`, `tabs`,
>   `languages`, or `versions`.