Skip to main content
The navigation property in docs.json controls the structure and information hierarchy of your documentation. With proper navigation configuration, you can organize your content so that users can find exactly what they’re looking for. Choose one primary organizational pattern at the root level of your navigation. Once you’ve chosen your primary pattern, you can nest other navigation elements within it.

​
Pages

Pages are the most fundamental navigation component. Each page is an MDX file in your documentation repository. In the navigation object, pages is an array where each entry must reference the path to a page file. 
{
  "navigation": {
    "pages": [
      "settings",
      "pages",
      "navigation",
      "themes",
      "custom-domain"
    ]
  }
}

​
Groups

Use groups to organize your sidebar navigation into sections. You can nest groups within each other, label them with tags, and style them with icons. In the navigation object, groups is an array where each entry is an object that requires a group field and a pages field. The icon, tag, root, and expanded fields are optional. 
{
  "navigation": {
    "groups": [
      {
        "group": "Getting started",
        "icon": "play",
        "pages": [
          "quickstart",
          {
            "group": "Editing",
            "expanded": false,
            "icon": "pencil",
            "pages": [
              "installation",
              "editor"
            ]
          }
        ]
      },
      {
        "group": "Writing content",
        "icon": "notebook-text",
        "tag": "NEW",
        "pages": [
          "writing-content/page",
          "writing-content/text"
        ]
      }
    ]
  }
}

​
Root page

Use the root property to designate a main page for a group. When a group has a root page, clicking the group title in the sidebar navigation opens the root page. 
{
  "navigation": {
    "groups": [
      {
        "group": "API pages",
        "root": "api-overview",
        "pages": [
          "api-reference/get",
          "api-reference/post",
          "api-reference/delete"
        ]
      }
    ]
  }
}

​
Default expanded state

Use the expanded property to control the default state of a nested group in the navigation sidebar.
The expanded property only affects nested groups—groups within groups. Top-level groups are always expanded and cannot be collapsed.
{
  "group": "Getting started",
  "pages": [
    "quickstart",
    {
      "group": "Advanced",
      "expanded": false,
      "pages": ["installation", "configuration"]
    }
  ]
}

​
Tabs

Tabs create distinct sections of your documentation with separate URL paths. Tabs create a horizontal navigation bar at the top of your documentation that lets users switch between sections. In the navigation object, tabs is an array where each entry is an object that requires a tab field and can contain other navigation fields such as groups, pages, icons, or links to external pages. 
{
  "navigation": {
    "tabs": [
      {
        "tab": "API reference",
        "icon": "square-terminal",
        "pages": [
          "api-reference/get",
          "api-reference/post",
          "api-reference/delete"
        ]
      },
      {
        "tab": "SDKs",
        "icon": "code",
        "pages": [
          "sdk/fetch",
          "sdk/create",
          "sdk/delete"
        ]
      },
      {
        "tab": "Blog",
        "icon": "newspaper",
        "href": "https://external-link.com/blog"
      }
    ]
  }
}
Menus add dropdown navigation items to a tab. Use menus to help users go directly to specific pages within a tab.
Menu items can only contain groups, pages, and external links.
{
  "navigation": {
    "tabs": [
      {
        "tab": "Developer tools",
        "icon": "square-terminal",
        "menu": [
          {
            "item": "API reference",
            "icon": "rocket",
            "groups": [
              {
                "group": "Core endpoints",
                "icon": "square-terminal",
                "pages": [
                  "api-reference/get",
                  "api-reference/post",
                  "api-reference/delete"
                ]
              }
            ]
          },
          {
            "item": "SDKs",
            "icon": "code",
            "description": "SDKs are used to interact with the API.",
            "pages": [
              "sdk/fetch",
              "sdk/create",
              "sdk/delete"
            ]
          }
        ]
      }
    ]
  }
}

​
Anchors

Anchors add persistent navigation items to the top of your sidebar. Use anchors to section your content, provide quick access to external resources, or create prominent calls to action. In the navigation object, anchors is an array where each entry is an object that requires an anchor field and can contain other navigation fields such as groups, pages, icons, or links to external pages. 
{
  "navigation": {
    "anchors": [
      {
        "anchor": "Documentation",
        "icon": "book-open",
        "pages": [
          "quickstart",
          "development",
          "navigation"
        ]
      },
      {
        "anchor": "API reference",
        "icon": "square-terminal",
        "pages": [
          "api-reference/get",
          "api-reference/post",
          "api-reference/delete"
        ]
      },
      {
        "anchor": "Blog",
        "href": "https://external-link.com/blog"
      }
    ]
  }
}

​
Global anchors

Use global anchors for links that should appear on all pages, regardless of which section of your navigation the user is viewing.
Global anchors are particularly useful for linking to resources outside your documentation (such as a blog, community forum, or support portal) or for providing consistent access to important internal pages (such as a changelog or status page).
{
  "navigation": {
    "global":  {
      "anchors": [
        {
          "anchor": "Changelog",
          "icon": "list",
          "href": "/changelog"
        },
        {
          "anchor": "Blog",
          "icon": "pencil",
          "href": "https://mintlify.com/blog"
        }
      ]
    },
    "tabs": []
  }
}
Dropdowns are an expandable menu at the top of your sidebar navigation. Each item in a dropdown directs to a section of your documentation. In the navigation object, dropdowns is an array where each entry is an object that requires a dropdown field and can contain other navigation fields such as groups, pages, icons, or links to external pages. 
{
  "navigation": {
    "dropdowns": [
      {
        "dropdown": "Documentation",
        "icon": "book-open",
        "pages": [
          "quickstart",
          "development",
          "navigation"
        ]
      },
      {
        "dropdown": "API reference",
        "icon": "square-terminal",
        "pages": [
          "api-reference/get",
          "api-reference/post",
          "api-reference/delete"
        ]
      },
      {
        "dropdown": "Blog",
        "href": "https://external-link.com/blog"
      }
    ]
  }
}

​
Products

Products create a dedicated navigation division for organizing product-specific documentation. Use products to separate different offerings, services, or major feature sets within your documentation. In the navigation object, products is an array where each entry is an object that requires a product field and can contain other navigation fields such as groups, pages, icons, or links to external pages. 
{
  "navigation": {
    "products": [
      {
        "product": "Core API",
        "description": "Core API description",    
        "icon": "api",
        "groups": [
          {
            "group": "Getting started",
            "pages": [
              "core-api/quickstart",
              "core-api/authentication"
            ]
          },
          {
            "group": "Endpoints",
            "pages": [
              "core-api/users",
              "core-api/orders"
            ]
          }
        ]
      },
      {
        "product": "Analytics Platform",
        "description": "Analytics Platform description",
        "icon": "chart-bar",
        "pages": [
          "analytics/overview",
          "analytics/dashboard",
          "analytics/reports"
        ]
      },
      {
        "product": "Mobile SDK",
        "description": "Mobile SDK description",
        "icon": "smartphone",
        "href": "https://mobile-sdk-docs.example.com"
      }
    ]
  }
}

​
OpenAPI

Integrate OpenAPI specifications directly into your navigation structure to automatically generate API documentation.
When you add the openapi property to a navigation element (such as an anchor, tab, or group) without specifying any pages, Mintlify automatically generates pages for all endpoints defined in your OpenAPI specification.To control which endpoints appear, explicitly list the desired endpoints in a pages array.
For more information about referencing OpenAPI endpoints in your docs, see the OpenAPI setup. 
{
  "navigation": {
    "groups": [
      {
        "group": "API reference",
        "openapi": "/path/to/openapi-v1.json",
        "pages": [
          "overview",
          "authentication",
          "GET /users",
          "POST /users",
          {
            "group": "Products",
            "openapi": "/path/to/openapi-v2.json",
            "pages": [
              "GET /products",
              "POST /products"
            ]
          }
        ]
      }
    ]
  }
}

​
Versions

Partition your navigation into different versions. Versions are selectable from a dropdown menu. In the navigation object, versions is an array where each entry is an object that requires a version field and can contain any other navigation fields. 
{
  "navigation": {
    "versions": [
      {
        "version": "1.0.0",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["v1/overview", "v1/quickstart", "v1/development"]
          }
        ]
      },
      {
        "version": "2.0.0",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["v2/overview", "v2/quickstart", "v2/development"]
          }
        ]
      }
    ]
  }
}

​
Version tags

Add a badge label to version entries in the version selector dropdown using the optional tag field. Use tags to highlight specific versions such as “Latest”, “Recommended”, or “Beta.” 
{
  "navigation": {
    "versions": [
      {
        "version": "2026_03",
        "tag": "Latest",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["getting-started", "quickstart"]
          }
        ]
      },
      {
        "version": "2025_12",
        "tag": "Recommended",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["2025_12/getting-started", "2025_12/quickstart"]
          }
        ]
      }
    ]
  }
}

​
Languages

Partition your navigation into different languages. Languages are selectable from a dropdown menu. In the navigation object, languages is an array where each entry is an object that requires a language field and can contain any other navigation fields, including language-specific banner configurations. 
{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "banner": {
          "content": "🚀 Version 2.0 is now live! See our [changelog](/en/changelog) for details.",
          "dismissible": true
        },
        "groups": [
          {
            "group": "Getting started",
            "pages": ["en/overview", "en/quickstart", "en/development"]
          }
        ]
      },
      {
        "language": "es",
        "banner": {
          "content": "🚀 ¡La versión 2.0 ya está disponible! Consulta nuestro [registro de cambios](/es/changelog).",
          "dismissible": true
        },
        "groups": [
          {
            "group": "Getting started",
            "pages": ["es/overview", "es/quickstart", "es/development"]
          }
        ]
      }
    ]
  }
}
For automated translations, contact the Mintlify sales team to discuss solutions.
Breadcrumbs display the full navigation path at the top of pages. Some themes have breadcrumbs enabled by default and others do not. 
"styling": {
  "eyebrows": "breadcrumbs"
}

​
Interaction configuration

Control how users interact with navigation elements using the interaction property in your docs.json.

​
Enable auto-navigation for groups

When a user expands a navigation group, some themes automatically navigate to the first page in the group. You can override a theme’s default behavior using the drilldown option. 
"interaction": {
  "drilldown": true
}
  • Set to true to force automatic navigation to the first page when a user selects a navigation group.
  • Set to false to prevent navigation and only expand or collapse the group when a user selects a navigation group.
  • Leave unset to use the theme’s default behavior.

Build docs developers (and LLMs) love

Get started for freeTalk to us