> ## Documentation Index > Fetch the complete documentation index at: https://wiki.another-horizon.eu/llms.txt > Use this file to discover all available pages before exploring further. # 导航 > 设计契合用户需求的信息架构。 `docs.json` 中的 [navigation](/zh/organize/settings#param-navigation) 属性用于控制文档的结构与信息层级。通过合理配置导航，你可以更好地组织内容，帮助用户迅速找到所需信息。在导航的根级选择一种主要的组织方式。确定主要方式后，你可以在其内部嵌套其他导航元素。

## 页面

页面是最基本的导航组件。每个页面都是文档存储库中的一个 MDX 文件。页面的装饰性图形。

在 `navigation` 对象中，`pages` 是一个数组，其中每个条目都必须指向一个[页面文件](/zh/organize/pages)的路径。 ```json theme={null} { "navigation": { "pages": [ "settings", "pages", "navigation", "themes", "custom-domain" ] } } ```

## 分组

使用分组将侧边栏导航组织成不同的部分。分组可以相互嵌套、使用标签进行标注，并配合 icon 展示样式。关于分组的装饰性图像。

在 `navigation` 对象中，`groups` 是一个数组，其中每一项都是一个对象，每个对象都必须包含 `group` 字段和 `pages` 字段。`icon`、`tag` 和 `expanded` 字段是可选的。 ```json theme={null} { "navigation": { "groups": [ { "group": "开始使用", "icon": "play", "pages": [ "quickstart", { "group": "编辑", "expanded": false, "icon": "pencil", "pages": [ "installation", "editor" ] } ] }, { "group": "编写内容", "icon": "notebook-text", "tag": "NEW", "pages": [ "writing-content/page", "writing-content/text" ] } ] } } ```

### 默认展开状态

使用 `expanded` 属性来控制导航侧边栏中嵌套分组的默认状态。 * `expanded: true`：分组默认处于展开状态。 * `expanded: false` 或省略：分组默认处于折叠状态。 `expanded` 属性只会影响嵌套分组——也就是分组中的分组。顶级分组始终是展开的，且无法折叠。 ```json theme={null} { "group": "开始使用", "pages": [ "quickstart", { "group": "高级功能", "expanded": false, "pages": ["installation", "configuration"] } ] } ```

## 选项卡

选项卡可为你的文档创建彼此独立的 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，或指向外部页面的链接。菜单项只能包含 groups、pages 和外部链接。 ```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" } ] } } ```

### 全局锚点

使用全局锚点为需要在所有页面中显示的外部链接提供入口，而不受用户当前查看的导航部分影响。全局锚点特别适合用于链接到文档之外的资源，例如博客、社区论坛或支持门户。全局锚点必须包含指向外部 URL 的 `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" } ] } } ```

## 产品

“产品”用于在导航中创建专门的分区，以组织针对特定产品的文档。使用“产品”将文档中的不同产品、服务或重要功能集彼此区分开。在 `navigation` 对象中，`products` 是一个数组，其中每个条目都是一个对象，必须包含 `product` 字段，并且可以包含其他导航字段，例如 groups、pages、icons，或指向外部页面的链接。 ```json theme={null} { "navigation": { "products": [ { "product": "Core API", "description": "核心 API 说明", "icon": "api", "groups": [ { "group": "快速入门", "pages": [ "core-api/quickstart", "core-api/authentication" ] }, { "group": "端点", "pages": [ "core-api/users", "core-api/orders" ] } ] }, { "product": "Analytics Platform", "description": "Analytics 平台说明", "icon": "chart-bar", "pages": [ "analytics/overview", "analytics/dashboard", "analytics/reports" ] }, { "product": "Mobile SDK", "description": "移动端 SDK 说明", "icon": "smartphone", "href": "https://mobile-sdk-docs.example.com" } ] } } ```

## OpenAPI

将 OpenAPI 规范直接集成到导航结构中，以自动生成 API 文档。你可以创建专门的 API 部分，或将端点（endpoint）页面放入其他导航组件中。可以在导航层级的任意级别设置一个默认的 OpenAPI 规范。子元素将继承该规范，除非它们定义了自己的规范。当你在某个导航元素（例如 anchor、tab 或 group）上添加 `openapi` 属性且未指定任何页面时，Mintlify 会自动为 OpenAPI 规范中定义的 **所有端点** 生成页面。若要控制显示哪些端点，请在 `pages` 数组中显式列出所需的端点。有关在文档中引用 OpenAPI 端点的更多信息，请参阅 [OpenAPI 设置](/zh/api-playground/openapi-setup)。 ```json theme={null} { "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" ] } ] } ] } } ```

## 版本

将导航划分为不同版本。可通过下拉菜单选择版本。版本切换器的装饰性图形

在 `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` 字段，并且可以包含任意其他导航字段，包括特定语言的横幅配置。我们目前支持以下语言的本地化： ```json theme={null} { "navigation": { "languages": [ { "language": "en", "banner": { "content": "🚀 Version 2.0 is now live! See our [changelog](/en/changelog) for details.", "dismissible": true }, "groups": [ { "group": "开始使用", "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 }, "groups": [ { "group": "开始使用", "pages": ["es/overview", "es/quickstart", "es/development"] } ] } ] } } ``` 如需自动翻译支持，请[联系销售团队](mailto:gtm@mintlify.com)以商讨解决方案。

## 嵌套

导航元素可以相互嵌套，以创建复杂的层级结构。你必须有一个根级父导航元素，例如 tabs、groups 或下拉菜单。你可以在主要导航结构中嵌套其他类型的导航元素。在导航层级结构的每一层中，每个导航元素只能包含一种类型的子元素。比如，一个 tab 可以包含锚点，锚点下面可以包含 groups，但一个 tab 不能在同一级同时包含锚点和 groups。 ```json 包含锚点的 Tabs theme={null} { "navigation": { "tabs": [ { "tab": "Documentation", "tabs": [ { "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 包含标签页的锚点 theme={null} { "navigation": { "tabs": [ { "anchor": "Documentation", "icon": "book-open", "tabs": [ { "tab": "Guides", "pages": ["quickstart", "tutorial"] }, { "tab": "API", "pages": ["api/overview", "api/endpoints"] } ] }, { "anchor": "Community", "icon": "users", "tab": "https://community.example.com" } ] } } ``` ```json 包含标签页的产品 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 具有标签页和菜单的多产品 SaaS 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 带有标签页的多版本文档 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"] } ] } ] } } ```

## 面包屑导航

面包屑导航会在页面顶部显示完整的导航路径。某些主题默认启用面包屑导航，另一些则未启用。你可以在 `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` 属性来控制用户与导航元素的交互方式。当用户展开一个导航分组时，某些主题会自动跳转到该分组中的第一页。你可以使用 `drilldown` 选项覆盖主题的默认行为。 * 设为 `true`：在选择导航分组时强制自动跳转到第一页。 * 设为 `false`：不进行跳转，选择时仅展开或折叠分组。 * 留空不设置：使用主题的默认行为。 ```json 强制导航 theme={null} "interaction": { "drilldown": true // 当用户展开下拉菜单时强制跳转到第一页 } ``` ```json 阻止导航 theme={null} "interaction": { "drilldown": false // 从不跳转，仅展开或折叠该分组 } ```