> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Navigation
> Configure your documentation site navigation with groups, pages, dropdowns, tabs, and anchors in docs.json to build a sidebar structure.
The [navigation](/organize/settings-structure#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](/organize/pages).
```json theme={null}
{
"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.
```json theme={null}
{
"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. Root pages work for top-level and nested groups.
```json Example group with a root page theme={null}
{
"navigation": {
"groups": [
{
"group": "API pages",
"root": "api-overview",
"pages": [
"api-reference/get",
"api-reference/post",
"api-reference/delete"
]
}
]
}
}
```
### Directory listings
Use the `directory` property to automatically render a directory of child pages and groups on group root pages. When you set `directory` on any object within the `navigation` tree in `docs.json`, groups with a `root` page matching or beneath that object display a listing of their pages and groups below their page contents.
The `directory` property accepts three values:
| Value | Behavior |
| :------------ | :------------------------------------------------------------- |
| `"none"` | No directory listing. Default value. |
| `"accordion"` | Displays child pages in a collapsible list grouped by section. |
| `"card"` | Displays child pages in a horizontal card layout. |
The `directory` value inherits recursively through the navigation tree. Set it on anywhere within the navigation object and all descendant groups inherit the same value. Any descendant can override the inherited value by setting `directory` to a different value.
You can set `directory` anywhere in the navigation object in your `docs.json` file, including on tabs, anchors, dropdowns, products, versions, languages, and individual groups.
```json theme={null}
{
"navigation": {
"groups": [
{
"group": "Help Center",
"root": "help/index",
"directory": "accordion",
"pages": [
{
"group": "Getting Started",
"root": "help/getting-started/index",
"pages": [
"help/getting-started/quickstart",
"help/getting-started/install"
]
},
{
"group": "API Reference",
"root": "help/api/index",
"directory": "none",
"pages": [
"help/api/overview",
"help/api/endpoints"
]
}
]
}
]
}
}
```
In this example:
* **Help Center** uses `"accordion"` and its root page displays a directory listing.
* **Getting Started** inherits `"accordion"` from its parent and also displays a directory listing.
* **API Reference** overrides with `"none"`, so its root page does not display a directory listing.
The `directory` property only affects groups that have a `root` page. Groups without a `root` page are not affected.
### Default expanded state
Use the `expanded` property to control the default state of a nested group in the navigation sidebar.
* `expanded: true`: Expands the group by default.
* `expanded: false` or omitted: Collapses the group by default.
The `expanded` property only affects nested groups--groups within groups. Top-level groups always expand and you cannot collapse them.
```json theme={null}
{
"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.
```json theme={null}
{
"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
Menus add dropdown navigation items to a tab. Use menus to help users go directly to specific pages within a tab.
In the `navigation` object, `menu` is an array where each entry is an object that requires an `item` field and can contain other navigation fields such as groups, pages, icons, or links to external pages.
Menu items can only contain groups, pages, and external links.
```json theme={null}
{
"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.
```json theme={null}
{
"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).
Global anchors support both external URLs and relative paths to pages within your documentation.
```json theme={null}
{
"navigation": {
"global": {
"anchors": [
{
"anchor": "Changelog",
"icon": "list",
"href": "/changelog"
},
{
"anchor": "Blog",
"icon": "pencil",
"href": "https://mintlify.com/blog"
}
]
},
"tabs": /*...*/
}
}
```
## 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.
```json theme={null}
{
"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"
}
]
}
}
```
## Dropdowns
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.
```json theme={null}
{
"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"
}
]
}
}
```
## OpenAPI
Integrate OpenAPI specifications directly into your navigation structure to automatically generate API documentation. Create dedicated API sections or place endpoint pages within other navigation components.
Set a default OpenAPI specification at any level of your navigation hierarchy. Child elements inherit the specification unless they define their own.
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](/api-playground/openapi-setup).
```json theme={null}
{
"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.
```json theme={null}
{
"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"]
}
]
}
]
}
}
```
### Default version
Mintlify uses the first version in the `versions` array as the default. Use the `default` field to specify a different version as the default.
```json theme={null}
{
"navigation": {
"versions": [
{
"version": "1.0.0",
"groups": [
{
"group": "Getting started",
"pages": ["v1/overview", "v1/quickstart"]
}
]
},
{
"version": "2.0.0",
"default": true,
"groups": [
{
"group": "Getting started",
"pages": ["v2/overview", "v2/quickstart"]
}
]
}
]
}
}
```
### 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."
```json theme={null}
{
"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"]
}
]
},
{
"version": "2025_09",
"tag": "Deprecated",
"groups": [
{
"group": "Getting started",
"pages": ["2025_09/getting-started", "2025_09/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, footer, and navbar configurations.
We currently support the following languages for localization:
| Language | Code |
| --------------------- | --------- |
| Arabic | `ar` |
| Catalan | `ca` |
| Chinese | `cn` |
| Chinese (Traditional) | `zh-Hant` |
| Czech | `cs` |
| Dutch | `nl` |
| English | `en` |
| Finnish | `fi` |
| French | `fr` |
| German | `de` |
| Hebrew | `he` |
| Hindi | `hi` |
| Hungarian | `hu` |
| Indonesian | `id` |
| Italian | `it` |
| Japanese | `jp` |
| Korean | `ko` |
| Latvian | `lv` |
| Norwegian | `no` |
| Polish | `pl` |
| Portuguese (Brazil) | `pt-BR` |
| Romanian | `ro` |
| Russian | `ru` |
| Spanish | `es` |
| Swedish | `sv` |
| Turkish | `tr` |
| Ukrainian | `uk` |
| Uzbek | `uz` |
| Vietnamese | `vi` |
```json theme={null}
{
"navigation": {
"languages": [
{
"language": "en",
"banner": {
"content": "🚀 Version 2.0 is now live! See our [changelog](/en/changelog) for details.",
"dismissible": true
},
"footer": {
"socials": {
"x": "https://x.com/mintlify"
},
"links": [
{
"header": "Resources",
"items": [
{ "label": "Documentation", "href": "/en/docs" },
{ "label": "Blog", "href": "https://mintlify.com/blog" }
]
}
]
},
"navbar": {
"links": [
{ "label": "Docs", "href": "/en/docs" }
],
"primary": {
"type": "button",
"label": "Get Started",
"href": "/en/quickstart"
}
},
"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
},
"footer": {
"socials": {
"x": "https://x.com/mintlify"
},
"links": [
{
"header": "Recursos",
"items": [
{ "label": "Documentación", "href": "/es/docs" },
{ "label": "Blog", "href": "https://mintlify.com/blog" }
]
}
]
},
"navbar": {
"links": [
{ "label": "Documentación", "href": "/es/docs" }
],
"primary": {
"type": "button",
"label": "Comenzar",
"href": "/es/quickstart"
}
},
"groups": [
{
"group": "Getting started",
"pages": ["es/overview", "es/quickstart", "es/development"]
}
]
}
]
}
}
```
For automated translations, [set up a workflow](/workflows) to run the agent on a schedule or in response to repository pushes.
## Nesting
You can nest navigation elements within each other to create complex hierarchies. You must have one root-level parent navigation element such as tabs, groups, or a dropdown. You can nest other types of navigation elements within your primary navigation pattern.
Each navigation element can contain one type of child element at each level of your navigation hierarchy. For example, a tab can contain anchors that contain groups, but a tab cannot contain both anchors and groups at the same level.
```json Tabs containing anchors theme={null}
{
"navigation": {
"tabs": [
{
"tab": "Documentation",
"anchors": [
{
"anchor": "Guides",
"icon": "book-open",
"pages": ["quickstart", "tutorial"]
},
{
"anchor": "API Reference",
"icon": "code",
"pages": ["api/overview", "api/endpoints"]
}
]
},
{
"tab": "Resources",
"groups": [
{
"group": "Help",
"pages": ["support", "faq"]
}
]
}
]
}
}
```
```json Anchors containing tabs theme={null}
{
"navigation": {
"anchors": [
{
"anchor": "Documentation",
"icon": "book-open",
"tabs": [
{
"tab": "Guides",
"pages": ["quickstart", "tutorial"]
},
{
"tab": "API",
"pages": ["api/overview", "api/endpoints"]
}
]
},
{
"anchor": "Community",
"icon": "users",
"href": "https://community.example.com"
}
]
}
}
```
```json Products containing tabs theme={null}
{
"navigation": {
"products": [
{
"product": "Platform",
"icon": "server",
"tabs": [
{
"tab": "Documentation",
"groups": [
{
"group": "Getting started",
"pages": ["platform/quickstart"]
}
]
},
{
"tab": "API Reference",
"pages": ["platform/api"]
}
]
},
{
"product": "Mobile SDK",
"icon": "mobile",
"pages": ["mobile/overview"]
}
]
}
}
```
```json Multi-product SaaS with tabs and menu theme={null}
{
"navigation": {
"products": [
{
"product": "Platform",
"icon": "cloud",
"tabs": [
{
"tab": "Documentation",
"menu": [
{
"item": "Getting Started",
"icon": "rocket",
"groups": [
{
"group": "Setup",
"pages": ["platform/install", "platform/config"]
},
{
"group": "Core Concepts",
"pages": ["platform/concepts/auth", "platform/concepts/data"]
}
]
},
{
"item": "Guides",
"icon": "book",
"pages": ["platform/guides/deployment", "platform/guides/scaling"]
}
]
},
{
"tab": "API Reference",
"groups": [
{
"group": "REST API",
"pages": ["platform/api/users", "platform/api/projects"]
},
{
"group": "GraphQL",
"pages": ["platform/api/graphql/queries", "platform/api/graphql/mutations"]
}
]
}
]
},
{
"product": "Analytics",
"icon": "chart-bar",
"tabs": [
{
"tab": "Documentation",
"groups": [
{
"group": "Getting Started",
"pages": ["analytics/quickstart", "analytics/setup"]
}
]
},
{
"tab": "API",
"pages": ["analytics/api/events", "analytics/api/reports"]
}
]
}
]
}
}
```
```json Versioned docs with tabs theme={null}
{
"navigation": {
"versions": [
{
"version": "v2.0",
"tabs": [
{
"tab": "Documentation",
"groups": [
{
"group": "Getting Started",
"pages": ["v2/quickstart", "v2/migration-from-v1"]
},
{
"group": "Features",
"pages": ["v2/features/auth", "v2/features/api"]
}
]
},
{
"tab": "API Reference",
"pages": ["v2/api/overview", "v2/api/endpoints"]
}
]
},
{
"version": "v1.0",
"tabs": [
{
"tab": "Documentation",
"groups": [
{
"group": "Getting Started",
"pages": ["v1/quickstart"]
}
]
},
{
"tab": "API Reference",
"pages": ["v1/api/overview"]
}
]
}
]
}
}
```
## Breadcrumbs
Breadcrumbs display the full navigation path at the top of pages. Some themes have breadcrumbs enabled by default and others do not. You can control whether breadcrumbs display on your site using the `styling` property in your `docs.json`.
```json Display full breadcrumbs theme={null}
"styling": {
"eyebrows": "breadcrumbs"
}
```
```json Display parent section only theme={null}
"styling": {
"eyebrows": "section"
}
```
## 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.
* 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.
```json Force navigation theme={null}
"interaction": {
"drilldown": true // Force navigation to first page when a user expands a dropdown
}
```
```json Prevent navigation theme={null}
"interaction": {
"drilldown": false // Never navigate, only expand or collapse the group
}
```
## Related topics
- [Tree](/docs/components/tree.md)
- [Troubleshooting](/docs/api-playground/troubleshooting.md)
- [Configurations](/docs/editor/configurations.md)