> ## Documentation Index
> Fetch the complete documentation index at: https://omer-914cc1c6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Navigation
> Structure and customize your documentation's navigation hierarchy
The [navigation](settings#param-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.
## Pages
Pages are the most fundamental navigation component. Pages map to the MDX files that make up your documentation.
In the `navigation` object, `pages` is an array where each entry must reference the path to a [page file](pages).
```json theme={null}
{
"navigation": {
"pages": [
"settings",
"pages",
"navigation",
"themes",
"custom-domain"
]
}
}
```
## Groups
Use groups to organize your sidebar navigation into sections. Groups can be nested within each other, labeled with tags, and styled 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`, and `expanded` fields are optional.
```json theme={null}
{
"navigation": {
"groups": [
{
"group": "Getting started",
"icon": "play",
"expanded": false,
"pages": [
"quickstart",
{
"group": "Editing",
"icon": "pencil",
"pages": [
"installation",
"editor"
]
}
]
},
{
"group": "Writing content",
"icon": "notebook-text",
"tag": "NEW",
"pages": [
"writing-content/page",
"writing-content/text"
]
}
]
}
}
```
### Default expanded state
Set `expanded: true` on a group to make it expanded by default in the navigation sidebar. This is useful for highlighting important sections or improving discoverability of key content.
```json theme={null}
{
"group": "Getting started",
"expanded": true,
"pages": ["quickstart", "installation"]
}
```
## 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.
```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"
}
]
}
}
```
For anchors that direct to external links only, use the `global` keyword. Anchors in a `global` object must have an `href` field and cannot point to a relative path.
Global anchors are particularly useful for linking to resources that are not part of your documentation, but should be readily accessible to your users like a blog or support portal
```json theme={null}
{
"navigation": {
"global": {
"anchors": [
{
"anchor": "Community",
"icon": "house",
"href": "https://slack.com"
},
{
"anchor": "Blog",
"icon": "pencil",
"href": "https://mintlify.com/blog"
}
]
},
"tabs": /*...*/
}
}
```
## Dropdowns
Dropdowns are contained in 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 will inherit this specification unless they define their own specification.
```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"
]
}
]
}
]
}
}
```
For more information about referencing OpenAPI endpoints in your docs, see the [OpenAPI setup](/api-playground/openapi-setup).
## 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"]
}
]
}
]
}
}
```
## 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.
We currently support the following languages for localization:
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
```json theme={null}
{
"navigation": {
"languages": [
{
"language": "en",
"groups": [
{
"group": "Getting started",
"pages": ["en/overview", "en/quickstart", "en/development"]
}
]
},
{
"language": "es",
"groups": [
{
"group": "Getting started",
"pages": ["es/overview", "es/quickstart", "es/development"]
}
]
}
]
}
}
```
For automated translations, [contact our sales team](mailto:gtm@mintlify.com) to discuss solutions.
## Nesting
You can use any combination of anchors, tabs, and dropdowns. The components can be nested within each other interchangeably to create your desired navigation structure.
```json Anchors theme={null}
{
"navigation": {
"anchors": [
{
"anchor": "Anchor 1",
"groups": [
{
"group": "Group 1",
"pages": [
"some-folder/file-1",
"another-folder/file-2",
"just-a-file"
]
}
]
},
{
"anchor": "Anchor 2",
"groups": [
{
"group": "Group 2",
"pages": [
"some-other-folder/file-1",
"various-different-folders/file-2",
"another-file"
]
}
]
}
]
}
}
```
```json Tabs theme={null}
{
"navigation": {
"tabs": [
{
"tab": "Tab 1",
"groups": [
{
"group": "Group 1",
"pages": [
"some-folder/file-1",
"another-folder/file-2",
"just-a-file"
]
}
]
},
{
"tab": "Tab 2",
"groups": [
{
"group": "Group 2",
"pages": [
"some-other-folder/file-1",
"various-different-folders/file-2",
"another-file"
]
}
]
}
]
}
}
```
```json Tabs with external anchor theme={null}
{
"navigation": {
"global": {
"anchors": [
{
"anchor": "Anchor 1",
"href": "https://mintlify.com/docs"
}
]
},
"tabs": [
{
"tab": "Tab 1",
"groups": [
{
"group": "Group 1",
"pages": [
"some-folder/file-1",
"another-folder/file-2",
"just-a-file"
]
}
]
},
{
"tab": "Tab 2",
"groups": [
{
"group": "Group 2",
"pages": [
"some-other-folder/file-1",
"various-different-folders/file-2",
"another-file"
]
}
]
}
]
}
}
```
## 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 are enabled for 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 will 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 navigation group is selected.
* Set to `false` to prevent navigation and only expand or collapse the group when it is selected.
* 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
}
```