> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blode.md/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Navigation

Configure sidebar groups, tabs, and page ordering in docs.json.

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`.