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

Collapsible sections within a tab:

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

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