Skip to content
Blode.md

AI agents: fetch the documentation index at llms.txt. Markdown versions are available by appending .md to any page URL, including this page's markdown.

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.

{
  "navigation": {
    "groups": [
      {
        "group": "Getting started",
        "pages": ["index", "quickstart"]
      },
      {
        "group": "Guides",
        "pages": ["guides/authentication", "guides/deployment"]
      }
    ]
  }
}
FieldTypeDescriptionRequired
groupstringDisplay label for the sidebar section.Yes
pagesstring[]Array of page slugs. Each slug maps to an MDX file relative to your docs root.Yes
expandedbooleanWhether the group is expanded by default. Defaults to `true` for the first group.Yes
hiddenbooleanHide this group from the sidebar while keeping its pages accessible by URL.Yes

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.

{
  "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"
      }
    ]
  }
}
FieldTypeDescriptionRequired
tabstringDisplay label for the tab. This is the `label` field in the schema.Yes
groupsArray<Group>Array of sidebar groups displayed when this tab is active.Yes
pagesstring[]Flat list of page slugs (alternative to groups for simple tabs).Yes
hrefstringExternal URL. When set, clicking the tab navigates away instead of showing a sidebar.Yes
iconstringIcon name displayed next to the tab label.Yes

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.

{
  "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.

{
  "group": "API reference",
  "openapi": "openapi.yaml"
}
FieldTypeDescriptionRequired
sourcestringPath to your OpenAPI spec file.Yes
basePathstringBase path prefix for generated page slugs.Yes
directorystringOutput directory for generated MDX files.Yes
includestring[]Filter to specific operations (e.g., `GET /users`).Yes

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.

{
  "navigation": {
    "tabs": [{ "$ref": "./nav/guides.json" }, { "$ref": "./nav/api.json" }]
  }
}
{
  "tab": "Guides",
  "groups": [{ "group": "Getting started", "pages": ["index", "quickstart"] }]
}

Versions

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

{
  "navigation": {
    "versions": [
      { "label": "v2.0", "url": "/v2" },
      { "label": "v1.0", "url": "/v1" }
    ],
    "groups": [...]
  }
}
FieldTypeDescriptionRequired
labelstringVersion label displayed in the dropdown.Yes
urlstringURL path or full URL for this version.Yes

Languages

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

{
  "navigation": {
    "languages": [
      { "label": "English", "url": "/en" },
      { "label": "Japanese", "url": "/ja", "locale": "ja" }
    ],
    "groups": [...]
  }
}
FieldTypeDescriptionRequired
labelstringLanguage name displayed in the selector.Yes
urlstringURL path or full URL for this language.Yes
localestringBCP 47 locale code (e.g., `ja`, `fr`, `zh-CN`).Yes

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.

{
  "navigation": {
    "global": {
      "anchors": [
        { "label": "Community", "href": "/community" },
        { "label": "Dashboard", "href": "/app" }
      ],
      "links": [
        { "label": "Blog", "href": "/blog" }
      ]
    },
    "groups": [...]
  }
}
FieldTypeDescriptionRequired
global.anchorsArray<{ label: string, href: string }>Persistent anchor links shown across all tabs.Yes
global.linksArray<{ label: string, href: string }>Additional navigation links shown globally.Yes

Complete navigation schema

The full navigation object supports all of the following fields:

FieldTypeDescriptionRequired
tabsArray<Tab>Top-level tabbed sections. Each tab has its own sidebar.Yes
groupsArray<Group>Sidebar groups when not using tabs.Yes
pagesstring[]Flat list of page slugs (simplest form, no grouping).Yes
hiddenstring[]Page slugs accessible by URL but not shown in the sidebar.Yes
versionsArray<{ label, url }>Version dropdown entries.Yes
languagesArray<{ label, url, locale? }>Language selector entries.Yes
global{ anchors?, links? }Global anchors and links visible across all tabs.Yes