> ## 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
> 构建并自定义文档的导航层级结构
`docs.json` 中的 [navigation](zh/settings#param-navigation) 属性用于控制文档的结构与信息层次。
通过合理的导航配置，你可以更好地组织内容，帮助用户快速找到他们需要的信息。
## 页面
页面是导航中最基础的组成部分。每个页面对应构成文档的 MDX 文件。
在 `navigation` 对象中，`pages` 是一个数组，其中每个条目都必须引用一个[页面文件](zh/pages)的路径。
```json theme={null}
{
"navigation": {
"pages": [
"settings",
"pages",
"navigation",
"themes",
"custom-domain"
]
}
}
```
## 组
使用组将侧边栏导航划分为多个部分。组可以彼此嵌套、添加标签，并设置图标样式。
在 `navigation` 对象中，`groups` 是一个数组，其中每个条目都是一个对象，且必须包含 `group` 和 `pages` 字段。`icon`、`tag` 和 `expanded` 字段为可选。
```json theme={null}
{
"navigation": {
"groups": [
{
"group": "快速入门",
"icon": "play",
"expanded": false,
"pages": [
"quickstart",
{
"group": "编辑",
"icon": "pencil",
"pages": [
"installation",
"editor"
]
}
]
},
{
"group": "编写内容",
"icon": "notebook-text",
"tag": "NEW",
"pages": [
"writing-content/page",
"writing-content/text"
]
}
]
}
}
```
### 默认展开状态
在某个分组上设置 `expanded: true`，即可使其在导航侧边栏中默认展开。这有助于突出重要部分，或提升关键内容的可发现性。
```json theme={null}
{
"group": "快速入门",
"expanded": true,
"pages": ["quickstart", "installation"]
}
```
## 选项卡
选项卡可将文档划分为彼此独立的板块，每个板块都有自己的 URL 路径。它会在文档顶部生成一条水平导航栏，方便用户在不同板块之间切换。
在 `navigation` 对象中，`tabs` 是一个数组，其中每个条目是一个对象，必须包含 `tab` 字段，并且可以包含其他导航字段，例如 groups、pages、icon，或指向外部页面的链接。
```json theme={null}
{
"navigation": {
"tabs": [
{
"tab": "API 参考",
"icon": "square-terminal",
"pages": [
"api-reference/get",
"api-reference/post",
"api-reference/delete"
]
},
{
"tab": "SDK",
"icon": "code",
"pages": [
"sdk/fetch",
"sdk/create",
"sdk/delete"
]
},
{
"tab": "博客",
"icon": "newspaper",
"href": "https://external-link.com/blog"
}
]
}
}
```
菜单会为某个标签页添加下拉式导航项。使用菜单可帮助用户在该标签页内直接跳转到特定页面。
在 `navigation` 对象中，`menu` 是一个数组，其中每个条目都是一个对象，必须包含 `item` 字段，并且还可以包含其他导航相关字段，例如 groups、pages、icons，或指向外部页面的链接。
```json theme={null}
{
"navigation": {
"tabs": [
{
"tab": "开发者工具",
"icon": "square-terminal",
"menu": [
{
"item": "API 参考",
"icon": "rocket",
"groups": [
{
"group": "核心端点",
"icon": "square-terminal",
"pages": [
"api-reference/get",
"api-reference/post",
"api-reference/delete"
]
}
]
},
{
"item": "SDK",
"icon": "code",
"description": "SDK 用于与 API 进行交互。",
"pages": [
"sdk/fetch",
"sdk/create",
"sdk/delete"
]
}
]
}
]
}
}
```
## 锚点
锚点会在侧边栏顶部添加常驻的导航项。你可以用锚点为内容分区、提供快速访问外部资源，或创建醒目的行动号召。
在 `navigation` 对象中，`anchors` 是一个数组，其中每一项是一个对象，必须包含 `anchor` 字段，并且可以包含其他导航字段，例如 groups、页面、icon，或指向外部页面的链接。
```json theme={null}
{
"navigation": {
"anchors": [
{
"anchor": "文档",
"icon": "book-open",
"pages": [
"quickstart",
"development",
"navigation"
]
},
{
"anchor": "API 参考",
"icon": "square-terminal",
"pages": [
"api-reference/get",
"api-reference/post",
"api-reference/delete"
]
},
{
"anchor": "博客",
"href": "https://external-link.com/blog"
}
]
}
}
```
对于仅指向外部链接的锚点，请使用 `global` 关键字。位于 `global` 对象中的锚点必须包含 `href` 字段，且不能指向相对路径。
全局锚点特别适用于链接到不属于你的文档、但应让用户易于访问的资源，例如博客或支持门户。
```json theme={null}
{
"navigation": {
"global": {
"anchors": [
{
"anchor": "社区",
"icon": "house",
"href": "https://slack.com"
},
{
"anchor": "博客",
"icon": "pencil",
"href": "https://mintlify.com/blog"
}
]
},
"tabs": /*...*/
}
}
```
## 下拉菜单
下拉菜单位于侧边栏导航顶部的可展开菜单中。下拉菜单中的每个项目都会跳转到文档的某个部分。
在 `navigation` 对象中，`dropdowns` 是一个数组，其中每个条目都是一个对象，必须包含 `dropdown` 字段，并且可以包含其他导航字段，例如 groups、pages、icons，或指向外部页面的链接。
```json theme={null}
{
"navigation": {
"dropdowns": [
{
"dropdown": "文档",
"icon": "book-open",
"pages": [
"quickstart",
"development",
"navigation"
]
},
{
"dropdown": "API 参考",
"icon": "square-terminal",
"pages": [
"api-reference/get",
"api-reference/post",
"api-reference/delete"
]
},
{
"dropdown": "博客",
"href": "https://external-link.com/blog"
}
]
}
}
```
## OpenAPI
将 OpenAPI 规范直接集成到你的导航结构中，自动生成 API 文档。你可以创建专门的 API 部分，或将端点页面放入其他导航组件中。
可在导航层级的任意层级设置默认 OpenAPI 规范。子元素会继承该规范，除非它们另行定义。
```json theme={null}
{
"navigation": {
"groups": [
{
"group": "API 参考",
"openapi": "/path/to/openapi-v1.json",
"pages": [
"overview",
"authentication",
"GET /users",
"POST /users",
{
"group": "产品",
"openapi": "/path/to/openapi-v2.json",
"pages": [
"GET /products",
"POST /products"
]
}
]
}
]
}
}
```
有关在文档中引用 OpenAPI 端点的更多信息，请参阅 [OpenAPI 设置](/zh/api-playground/openapi-setup)。
## 版本
将导航划分为不同版本。可以通过下拉菜单进行选择。
在 `navigation` 对象中，`versions` 是一个数组，其中每个项都是一个对象，必须包含 `version` 字段，并且可以包含其他任意导航字段。
```json theme={null}
{
"navigation": {
"versions": [
{
"version": "1.0.0",
"groups": [
{
"group": "快速入门",
"pages": ["v1/overview", "v1/quickstart", "v1/development"]
}
]
},
{
"version": "2.0.0",
"groups": [
{
"group": "快速入门",
"pages": ["v2/overview", "v2/quickstart", "v2/development"]
}
]
}
]
}
}
```
## 语言
将导航按语言分区。可以从下拉菜单中选择语言。
在 `navigation` 对象中，`languages` 是一个数组，其中每个条目都是一个对象，必须包含 `language` 字段，并且可以包含任何其他导航字段。
我们目前支持以下本地化语言：
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
} horizontal />
```json theme={null}
{
"navigation": {
"languages": [
{
"language": "en",
"groups": [
{
"group": "开始使用",
"pages": ["en/overview", "en/quickstart", "en/development"]
}
]
},
{
"language": "es",
"groups": [
{
"group": "开始使用",
"pages": ["es/overview", "es/quickstart", "es/development"]
}
]
}
]
}
}
```
如需自动翻译，[请联系销售团队](mailto:gtm@mintlify.com)以讨论解决方案。
## 嵌套
你可以任意组合使用锚点、选项卡和下拉菜单。这些组件可以相互嵌套，以构建所需的导航结构。
```json 锚点 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 选项卡 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 带外部锚点的选项卡 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"
]
}
]
}
]
}
}
```
## 面包屑
面包屑会在页面顶部显示完整的导航路径。部分主题默认启用面包屑，部分则未启用。你可以通过在 `docs.json` 中设置 `styling` 属性来控制站点是否启用面包屑。
```json Display full breadcrumbs theme={null}
"styling": {
"eyebrows": "breadcrumbs"
}
```
```json Display parent section only theme={null}
"styling": {
"eyebrows": "section"
}
```
## 交互配置
在 `docs.json` 中通过 `interaction` 属性控制用户与导航元素的交互方式。
### 为 groups 启用自动导航
当用户展开一个导航分组时，某些主题会自动跳转到该分组中的第一个页面。你可以使用 `drilldown` 选项覆盖主题的默认行为。
* 设为 `true`：在选择导航分组时，强制自动跳转到第一个页面。
* 设为 `false`：不进行跳转，仅在选择时展开或折叠分组。
* 不设置：使用主题的默认行为。
```json Force navigation theme={null}
"interaction": {
"drilldown": true // 当用户展开下拉列表时，强制跳转到第一个页面
}
```
```json Prevent navigation theme={null}
"interaction": {
"drilldown": false // 始终不跳转，仅展开或折叠分组
}
```