mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Ethan Palm
82605179c5
* add icon info to tabs page * add icons to tabs example * update allowed icon type
522 lines
12 KiB
Plaintext
522 lines
12 KiB
Plaintext
---
|
|
title: "Navigation"
|
|
description: "Structure and customize your documentation's navigation hierarchy"
|
|
icon: "map"
|
|
---
|
|
|
|
The [navigation](settings#param-navigation) property in [docs.json](settings) defines how users will browse through your documentation. Think of it as the blueprint for your documentation's menu structure.
|
|
|
|
With proper navigation configuration, you can organize your content into a logical hierarchy that makes it easy for users to find exactly what they're looking for.
|
|
|
|
<Info>
|
|
Do not use `api` as a title for any navigation element. The `/api` path is reserved in production and will cause pages to return 404 errors if their URLs contain `/api`.
|
|
</Info>
|
|
|
|
## Pages
|
|
|
|
Pages are the most fundamental navigation component.
|
|
|
|
<img
|
|
className="block dark:hidden pointer-events-none"
|
|
src="/images/navigation/pages-light.png"
|
|
/>
|
|
|
|
<img
|
|
className="hidden dark:block pointer-events-none"
|
|
src="/images/navigation/pages-dark.png"
|
|
/>
|
|
|
|
Pages is an array where each entry must be a reference to the path of a [page file](pages).
|
|
|
|
```json
|
|
{
|
|
"navigation": {
|
|
"pages": [
|
|
"overview",
|
|
"quickstart",
|
|
"advanced/components",
|
|
"advanced/integrations"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Groups
|
|
|
|
Use groups to organize your navigation into sections. Groups can be nested within each other, labeled with tags, and styled with icons.
|
|
|
|
<img
|
|
className="block dark:hidden pointer-events-none"
|
|
src="/images/navigation/groups-light.png"
|
|
/>
|
|
|
|
<img
|
|
className="hidden dark:block pointer-events-none"
|
|
src="/images/navigation/groups-dark.png"
|
|
/>
|
|
|
|
```json
|
|
{
|
|
"navigation": {
|
|
"groups": [
|
|
{
|
|
"group": "Getting Started",
|
|
"icon": "play",
|
|
"pages": [
|
|
"quickstart",
|
|
{
|
|
"group": "Editing",
|
|
"icon": "pencil",
|
|
"pages": [
|
|
"installation",
|
|
"editor",
|
|
{
|
|
"group": "Nested group",
|
|
"icon": "code",
|
|
"pages": [
|
|
"navigation",
|
|
"code"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"group": "Writing Content",
|
|
"icon": "notebook-text",
|
|
"tag": "NEW",
|
|
"pages": ["writing-content/page", "writing-content/text"]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Tabs
|
|
|
|
Tabs help distinguish between different topics or sections of your
|
|
documentation.
|
|
|
|
<img
|
|
className="block dark:hidden pointer-events-none"
|
|
src="/images/navigation/tabs-light.png"
|
|
/>
|
|
|
|
<img
|
|
className="hidden dark:block pointer-events-none"
|
|
src="/images/navigation/tabs-dark.png"
|
|
/>
|
|
|
|
```json
|
|
"navigation": {
|
|
"tabs": [
|
|
{
|
|
"tab": "API References",
|
|
"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"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Anchors
|
|
|
|
Anchors are another way to section your content. They show up on top of your side navigation.
|
|
|
|
<img
|
|
className="block dark:hidden pointer-events-none"
|
|
src="/images/navigation/anchors-light.png"
|
|
/>
|
|
|
|
<img
|
|
className="hidden dark:block pointer-events-none"
|
|
src="/images/navigation/anchors-dark.png"
|
|
/>
|
|
|
|
The configuration is very similar to tabs.
|
|
|
|
While not required, we highly recommend that you set an `icon` field as well.
|
|
|
|
```json
|
|
"navigation": {
|
|
"anchors": [
|
|
{
|
|
"anchor": "Documentation",
|
|
"icon": "book-open",
|
|
"pages": [
|
|
"quickstart",
|
|
"development",
|
|
"navigation"
|
|
]
|
|
},
|
|
{
|
|
"anchor": "API References",
|
|
"icon": "square-terminal",
|
|
"pages": [
|
|
"api-reference/get",
|
|
"api-reference/post",
|
|
"api-reference/delete"
|
|
]
|
|
},
|
|
{
|
|
"anchor": "Blog",
|
|
"href": "https://external-link.com/blog"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
Anchors that strictly contain external links can be achieved using the `global` keyword:
|
|
|
|
```json
|
|
"navigation": {
|
|
"global": {
|
|
"anchors": [
|
|
{
|
|
"anchor": "Community",
|
|
"icon": "house",
|
|
"href": "https://slack.com"
|
|
},
|
|
{
|
|
"anchor": "Blog",
|
|
"icon": "pencil",
|
|
"href": "https://mintlify.com/blog"
|
|
}
|
|
]
|
|
},
|
|
"tabs": /*...*/
|
|
}
|
|
```
|
|
|
|
## Dropdowns
|
|
|
|
Dropdowns show up in the same place as anchors, but are consolidated into a single dropdown.
|
|
|
|
<img
|
|
className="block dark:hidden pointer-events-none"
|
|
src="/images/navigation/dropdowns-light.png"
|
|
/>
|
|
|
|
<img
|
|
className="hidden dark:block pointer-events-none"
|
|
src="/images/navigation/dropdowns-dark.png"
|
|
/>
|
|
|
|
While not required, we also recommend that you set an icon for each dropdown item.
|
|
|
|
```json
|
|
"navigation": {
|
|
"dropdowns": [
|
|
{
|
|
"dropdown": "Documentation",
|
|
"icon": "book-open",
|
|
"pages": [
|
|
"quickstart",
|
|
"development",
|
|
"navigation"
|
|
]
|
|
}
|
|
{
|
|
"dropdown": "API References",
|
|
"icon": "square-terminal",
|
|
"pages": [
|
|
"api-reference/get",
|
|
"api-reference/post",
|
|
"api-reference/delete"
|
|
]
|
|
}
|
|
{
|
|
"dropdown": "Blog",
|
|
"href": "https://external-link.com/blog"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Versions
|
|
|
|
Versions can be leveraged to partition your navigation into different versions.
|
|
|
|
<img
|
|
className="block dark:hidden pointer-events-none"
|
|
src="/images/navigation/versions-light.png"
|
|
/>
|
|
|
|
<img
|
|
className="hidden dark:block pointer-events-none"
|
|
src="/images/navigation/versions-dark.png"
|
|
/>
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
Languages can be leveraged to partition your navigation into different languages.
|
|
|
|
<img
|
|
className="block dark:hidden pointer-events-none"
|
|
src="/images/navigation/languages-light.png"
|
|
/>
|
|
|
|
<img
|
|
className="hidden dark:block pointer-events-none"
|
|
src="/images/navigation/languages-dark.png"
|
|
/>
|
|
|
|
We currently support the following languages:
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Arabic (ar)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/ar.png" className="w-6 h-6 my-0" />} horizontal>
|
|
|
|
</Card>
|
|
<Card title="Chinese (cn)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/cn.png" className="w-6 h-6 my-0" />} horizontal>
|
|
|
|
</Card>
|
|
<Card title="Chinese (zh-Hant)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/cn.png" className="w-6 h-6 my-0" />} horizontal>
|
|
|
|
</Card>
|
|
<Card title="English (en)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/en.png" className="w-6 h-6 my-0" />} horizontal>
|
|
|
|
</Card>
|
|
<Card title="French (fr)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/fr.png" className="w-6 h-6 my-0" />} horizontal>
|
|
|
|
</Card>
|
|
<Card title="German (de)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/de.png" className="w-6 h-6 my-0" />} horizontal>
|
|
|
|
</Card>
|
|
<Card title="Indonesian (id)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/id.png" className="w-6 h-6 my-0" />} horizontal>
|
|
|
|
</Card>
|
|
<Card title="Italian (it)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/it.png" className="w-6 h-6 my-0" />} horizontal>
|
|
|
|
</Card>
|
|
<Card title="Japanese (jp)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/jp.png" className="w-6 h-6 my-0" />} horizontal>
|
|
|
|
</Card>
|
|
<Card title="Korean (ko)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/ko.png" className="w-6 h-6 my-0" />} horizontal>
|
|
|
|
</Card>
|
|
<Card title="Portuguese (pt)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/pt.png" className="w-6 h-6 my-0" />} horizontal>
|
|
|
|
</Card>
|
|
<Card title="Portuguese (pt-BR)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/pt-br.png" className="w-6 h-6 my-0" />} horizontal>
|
|
|
|
</Card>
|
|
<Card title="Russian (ru)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/ru.png" className="w-6 h-6 my-0" />} horizontal>
|
|
|
|
</Card>
|
|
<Card title="Spanish (es)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/es.png" className="w-6 h-6 my-0" />} horizontal>
|
|
|
|
</Card>
|
|
<Card title="Turkish (tr)" icon={<img src="https://mintlify.s3.us-west-1.amazonaws.com/mintlify/images/navigation/languages/tr.png" className="w-6 h-6 my-0" />} horizontal>
|
|
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
```json
|
|
{
|
|
"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"]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Nesting
|
|
|
|
It's important to note that you can use any combination of anchors, tabs, and dropdowns - either one can be nested within each other interchangeably.
|
|
|
|
This way, you can create a very complex navigation structure that is easy to manage.
|
|
|
|
<CodeGroup>
|
|
|
|
```json Anchors
|
|
{
|
|
"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
|
|
{
|
|
"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 anchors
|
|
{
|
|
"navigation": {
|
|
"tabs": [
|
|
{
|
|
"tab": "Tab 1",
|
|
"global": {
|
|
"anchors": [
|
|
{
|
|
"anchor": "Anchor 1",
|
|
"href": "https://mintlify.com/docs"
|
|
}
|
|
]
|
|
},
|
|
"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"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
</CodeGroup> |