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.


{
  "navigation": {
    "groups": [
      {
        "group": "Getting started",
        "pages": ["index", "quickstart"]
      },
      {
        "group": "Guides",

Published with Blode.md

Navigation · Blode.md

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


{
  "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"
      }
    ]
  }
}

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

Field	Type	Description	Required
`source`	string	Path to your OpenAPI spec file.	Yes
`basePath`	string	Base path prefix for generated page slugs.	Yes
`directory`	string	Output directory for generated MDX files.	Yes
`include`	string[]	Filter to specific operations (e.g., `GET /users`).	Yes

Field	Type	Description	Required
`label`	string	Version label displayed in the dropdown.	Yes
`url`	string	URL path or full URL for this version.	Yes

Field	Type	Description	Required
`label`	string	Language name displayed in the selector.	Yes
`url`	string	URL path or full URL for this language.	Yes
`locale`	string	BCP 47 locale code (e.g., `ja`, `fr`, `zh-CN`).	Yes


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

Field	Type	Description	Required
`global.anchors`	Array<{ label: string, href: string }>	Persistent anchor links shown across all tabs.	Yes
`global.links`	Array<{ label: string, href: string }>	Additional navigation links shown globally.	Yes

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

Navigation

Groups

Navigation

Groups

Directory paths

Tabs

Hidden pages

OpenAPI auto-generated pages

Splitting navigation with $ref

Versions

Languages

Global anchors

Complete navigation schema