Set up sidebar navigation for your Mintlify docs

Organize your Mintlify pages into groups, tabs, and nested sections in the sidebar by defining the navigation object in docs.json.

Navigation in Mintlify is defined in the navigation field of your docs.json file. It controls what appears in the sidebar, in what order, and how pages are grouped. Every page you want visible to users must be listed here — pages omitted from navigation are hidden from the sidebar but still accessible via direct URL and search.

How navigation works

Each entry in navigation points to an MDX file by its path relative to the repository root, without the .mdx extension. For example, a file at guides/quickstart.mdx is referenced as "guides/quickstart".

Mintlify supports several navigation patterns. The most common are groups (a single section with organized pages) and tabs (multiple top-level sections that switch the sidebar content). Choose the pattern that fits how your content is organized.

Basic navigation with groups

Use groups to organize pages into labeled sections within a single sidebar. This is the right choice for most docs sites.

docs.json

{
  "navigation": {
    "groups": [
      {
        "group": "Getting started",
        "icon": "rocket",
        "pages": ["index", "quickstart", "installation"]
      },
      {
        "group": "Guides",
        "icon": "book-open",
        "pages": [
          "guides/authentication",
          "guides/pagination",
          "guides/error-handling"
        ]
      }
    ]
  }
}

Each group requires a group name and a pages array. You can optionally add an icon from the Lucide or Font Awesome icon libraries.

Navigation with tabs

Use tabs when your docs have distinct sections for different audiences or content types — for example, a user guide and an API reference. Each tab gets its own sidebar.

docs.json

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "icon": "book-open",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["index", "quickstart"]
          },
          {
            "group": "Guides",
            "pages": ["guides/overview", "guides/authentication"]
          }
        ]
      },
      {
        "tab": "API reference",
        "icon": "square-terminal",
        "groups": [
          {
            "group": "Endpoints",
            "pages": ["api-reference/overview", "api-reference/users", "api-reference/projects"]
          }
        ]
      }
    ]
  }
}

Do not use api as a top-level folder name in your repository. Next.js reserves this path, which causes conflicts. Use api-reference or another name instead.

Nested navigation

You can nest groups inside a pages array to create sub-sections within a group. Nested groups are collapsed by default.

docs.json

{
  "navigation": {
    "groups": [
      {
        "group": "Guides",
        "pages": [
          "guides/overview",
          {
            "group": "Advanced",
            "expanded": false,
            "pages": [
              "guides/advanced/webhooks",
              "guides/advanced/rate-limits",
              "guides/advanced/idempotency"
            ]
          }
        ]
      }
    ]
  }
}

Set "expanded": true on a nested group to have it open by default. Top-level groups are always expanded.

Using folders

Organize your MDX files into folders to keep the repository tidy. The folder structure does not need to match the navigation structure — you can arrange groups and pages in any order regardless of where the files live on disk.

A common pattern is to mirror the folder structure in navigation:

docs/
├── docs.json
├── index.mdx
├── quickstart.mdx
├── guides/
│   ├── authentication.mdx
│   ├── pagination.mdx
│   └── advanced/
│       └── webhooks.mdx
└── api-reference/
    ├── overview.mdx
    └── users.mdx

Reference each file by its path without the extension:

docs.json

{
  "navigation": {
    "groups": [
      {
        "group": "Guides",
        "pages": [
          "guides/authentication",
          "guides/pagination",
          "guides/advanced/webhooks"
        ]
      },
      {
        "group": "API reference",
        "pages": [
          "api-reference/overview",
          "api-reference/users"
        ]
      }
    ]
  }
}

Hidden pages

Any MDX file not listed in navigation is hidden from the sidebar but remains accessible by direct URL and through the search bar. Use this for pages that should exist but not be prominently linked — for example, changelogs, legal pages, or draft content.

You can also explicitly mark a page as hidden using the hidden frontmatter field:

---
title: "Internal reference"
hidden: true
---

This keeps the page out of the sidebar while keeping it reachable by URL.

Files placed in the snippets/ directory are never rendered as standalone pages. They are only used as imported components within other MDX files.