> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-mintlify-add-hello-world-quickstart-48843.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 导航
> 构建与自定义文档的导航层级
`docs.json` 中的 [navigation](zh/settings#param-navigation) 属性用于控制文档的结构与信息层级。
通过合理配置导航，你可以更好地组织内容，帮助用户快速找到所需信息。
## 页面
页面是最基础的导航单元。它们对应你文档中的 MDX 文件。
在 `navigation` 对象中，`pages` 是一个数组，其中每个条目都必须引用一个[页面文件](zh/pages)的路径。
```json
{
"navigation": {
"pages": [
"设置",
"页面",
"导航",
"主题",
"自定义域"
]
}
}
```
## 分组
使用分组将侧边栏导航组织成多个部分。分组可以相互嵌套、添加标签，并搭配图标展示样式。
在 `navigation` 对象中，`groups` 是一个数组，其中每个项都是一个对象，且必须包含 `group` 和 `pages` 字段。`icon`、`tag` 和 `expanded` 字段为可选。
```json
{
"navigation": {
"groups": [
{
"group": "快速开始",
"icon": "play",
"expanded": false,
"pages": [
"quickstart",
{
"group": "编辑",
"icon": "pencil",
"pages": [
"installation",
"editor"
]
}
]
},
{
"group": "内容创作",
"icon": "notebook-text",
"tag": "新"
"pages": [
"writing-content/page",
"writing-content/text"
]
}
]
}
}
```
### 默认展开状态
在分组上设置 `expanded: true`，即可让它在导航侧边栏中默认展开。这有助于突出重要部分，或提升关键内容的可发现性。
```json
{
"group": "快速上手",
"expanded": true,
"pages": ["快速上手", "安装"]
}
```
## 选项卡
选项卡可为文档创建相互独立的部分，并具备各自的 URL 路径。它们会在文档顶部生成一条水平导航栏，便于用户在不同部分之间切换。
在 `navigation` 对象中，`tabs` 是一个数组，其中每个项都是一个对象，必须包含 `tab` 字段，并可包含其他导航字段，例如分组、页面、图标或外部链接。
```json
{
"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` 字段，并且可以包含其他导航字段，例如分组、页面、图标或指向外部页面的链接。
```json
{
"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` 字段，并且可以包含其他导航字段，例如分组、页面、图标或指向外部页面的链接。
```json
{
"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
{
"navigation": {
"global": {
"anchors": [
{
"anchor": "社区",
"icon": "house",
"href": "https://slack.com"
},
{
"anchor": "博客",
"icon": "pencil",
"href": "https://mintlify.com/blog"
}
]
},
"tabs": /*...*/
}
}
```
## 下拉菜单
下拉菜单位于侧边栏导航顶部的可展开菜单中。下拉中的每一项都会跳转到文档的某个部分。
在 `navigation` 对象中，`dropdowns` 是一个数组，每个元素都是一个对象，必须包含 `dropdown` 字段，并且可以包含其他导航字段，例如分组、页面、图标或外部链接。
```json
{
"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
{
"navigation": {
"groups": [
{
"group": "API 参考",
"openapi": "/path/to/openapi-v1.json",
"pages": [
"总览",
"身份认证",
"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
{
"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
{
"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 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 anchor
{
"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
"styling": {
"eyebrows": "breadcrumbs"
}
```
```json Display parent section only
"styling": {
"eyebrows": "section"
}
```
## 交互配置
在 `docs.json` 中通过 `interaction` 属性控制用户与导航元素的交互方式。
### 为分组启用自动导航
当用户展开一个导航分组时，某些主题会自动跳转到该分组中的第一个页面。你可以通过 `drilldown` 选项覆盖主题的默认行为。
* 设为 `true`：在选择导航分组时强制跳转到第一个页面。
* 设为 `false`：不进行跳转，只在选择时展开或收起该分组。
* 不设置：使用主题的默认行为。
```json 强制导航
"interaction": {
"drilldown": true // 当用户展开分组时，强制跳转到第一个页面
}
```
```json 阻止导航
"interaction": {
"drilldown": false // 从不跳转，只展开或收起该分组
}
```