Navigation

Your sidebar and top bar are defined entirely in docs.json. The navigation hierarchy has three levels -- tabs for top-level sections, groups for collapsible folders, and pages for individual entries -- plus anchors for external links that appear on every page.

Structure Overview

docs.json

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "icon": "book-open",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      }
    ]
  }
}

Concepts

Tabs

Top-level navigation sections. Control their position with the tabsPosition setting:

Value	Position
`"top"`	In the header tab bar
`"left"`	At the top of the sidebar

The default position depends on your theme:

Theme	Default
jam	`"left"`
nebula	`"left"`
pulsar	`"top"`

{
  "tabsPosition": "left",
  "navigation": {
    "tabs": [
      { "tab": "Guides", "icon": "book", "groups": [...] },
      { "tab": "API", "icon": "code", "groups": [...] }
    ]
  }
}

Icons use the Font Awesome Light variant to maintain a clean, consistent appearance.

External Links (Anchors)

Add external links that appear at the top of the sidebar on all pages:

{
  "anchors": [
    { "name": "Blog", "href": "https://blog.example.com", "icon": "newspaper" },
    { "name": "Status", "href": "https://status.example.com", "icon": "signal" }
  ]
}

Field	Type	Required	Description
`name`	string	Yes	Display text for the link
`href`	string	Yes	URL (opens in new tab)
`icon`	string	No	Font Awesome icon name

Groups

A group is a labeled set of sidebar entries inside a tab. Groups give your sidebar a two-level rhythm and let you hide deeper sections behind accordion-style folders.

{
  "group": "Authentication",
  "pages": ["auth/overview", "auth/tokens"]
}

Two rendering tiers

The sidebar shows top-level and nested groups differently:

Tier	Where it appears	Behavior
Top-level group	Directly under a tab in `docs.json`	Acts as a persistent section header. Always shows its pages. Clicking the header jumps to the first page in the group.
Nested group	Inside another group's `pages` array	Renders as an accordion-style folder with a chevron toggle. Click to expand or collapse.

A group's tier is positional: the outermost groups under a tab render as top-level, and any group placed inside another group's pages array renders as a nested folder. There is no topLevel flag.

Use top-level groups for the major sections of your sidebar (Get Started, Reference, Guides) and nested groups when a top-level section has enough pages that a second level of hierarchy helps the reader scan. See Nested Groups for the JSON shape.

How nested groups behave

Sidebar with the 'Privacy & Access' nested group collapsed: chevron points right, child pages hidden — A nested group in its collapsed state. The chevron points right and the child pages are hidden.

Auto-expand to the current page. The group containing the page you are viewing opens automatically, so the active link is always visible.
Click to toggle. Clicking a nested group's header expands it (and navigates to its first page) or collapses it if it is already open.
State persists across in-app navigation. Groups you manually open stay open as you move between pages. A full page refresh resets the open/closed state.

Sidebar with the 'Privacy & Access' nested group expanded: chevron rotated down, three child pages visible below — The same group after navigating to one of its child pages. The chevron rotates and the child pages appear below.

Group fields

Field	Type	Required	Description
`group`	string	Yes	Display label shown in the sidebar.
`pages`	array	Yes	List of page paths and/or nested group objects (see Nested Groups for the nested shape).
`icon`	string	No	Font Awesome icon name displayed beside the group label.
`tag`	string	No	Small badge next to the label (e.g., `"New"`, `"Beta"`).
`root`	string	No	Page path the group links to when the label is clicked (instead of jumping to the first child page).
`hidden`	boolean	No	Hide the group from the sidebar by default. The pages remain reachable by direct link.
`public`	boolean	No	Mark the group as publicly accessible. Defaults to the parent tab's setting.
`expanded`	boolean	No	Open the group by default on first page load. Only meaningful for nested groups (top-level groups always show their pages).

Pages

Individual documentation pages, referenced by their file path (without .mdx):

"pages": ["introduction", "guides/quickstart", "api/endpoints"]

By default, the sidebar title is generated from the file name -- dashes become spaces and each word is capitalized. For example, "api/getting-started" displays as "Getting Started".

To set a custom sidebar title, use an object instead of a string:

"pages": [
  "guides/quickstart",
  { "page": "deploy/aws", "title": "AWS Route 53 & CloudFront" },
  { "page": "content/seo", "title": "SEO" },
  { "page": "api/users", "title": "List Users", "method": "GET" }
]

This is useful for acronyms, proper nouns, and API endpoint badges.

Field	Type	Required	Description
`page`	string	Yes	File path without `.mdx`
`title`	string	No	Custom sidebar title
`icon`	string	No	Font Awesome icon name
`tag`	string	No	Small badge next to the title (e.g., "New", "Beta")
`method`	string	No	HTTP method badge: GET, POST, PUT, PATCH, or DELETE

Multiple Tabs

Create separate sections for different audiences:

{
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "icon": "book",
        "groups": [
          { "group": "Getting Started", "pages": ["intro", "quickstart"] }
        ]
      },
      {
        "tab": "API Reference",
        "icon": "code",
        "groups": [{ "group": "Endpoints", "pages": ["api/auth", "api/users"] }]
      }
    ]
  }
}

External Tab Links

Link to external documentation or resources directly from tabs:

{
  "navigation": {
    "tabs": [
      { "tab": "Docs", "icon": "book", "groups": [...] },
      { "tab": "GitHub", "icon": "github", "href": "https://github.com/example/repo" }
    ]
  }
}

External tabs open in a new browser tab.

Nested Groups

Organize complex documentation with nested structures:

{
  "group": "SDKs",
  "pages": [
    "sdks/overview",
    {
      "group": "JavaScript",
      "pages": ["sdks/js/install", "sdks/js/usage"]
    },
    {
      "group": "Python",
      "pages": ["sdks/python/install", "sdks/python/usage"]
    }
  ]
}

What's Next?

Connect GitHub

Link your repository for automatic builds

Directory Structure

Organize your docs for scale