docs.json 中的 navigation 属性用于控制文档的结构与信息层级。
通过合理配置导航，你可以更好地组织内容，帮助用户迅速找到所需信息。
在导航的根级选择一种主要的组织方式。确定主要方式后，你可以在其内部嵌套其他导航元素。
页面是最基本的导航组件。每个页面都是文档存储库中的一个 MDX 文件。
在 navigation 对象中，pages 是一个数组，其中每个条目都必须指向一个页面文件的路径。
{
"navigation": {
"pages": [
"settings",
"pages",
"navigation",
"themes",
"custom-domain"
]
}
}
在 navigation 对象中，groups 是一个数组，其中每一项都是一个对象，每个对象都必须包含 group 字段和 pages 字段。icon、tag 和 expanded 字段是可选的。
{
"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 属性只会影响嵌套分组——也就是分组中的分组。顶级分组始终是展开的，且无法折叠。
{
"group": "开始使用",
"pages": [
"quickstart",
{
"group": "高级功能",
"expanded": false,
"pages": ["installation", "configuration"]
}
]
}
在 navigation 对象中，tabs 是一个数组，其中每个项都是一个对象，必须包含 tab 字段，并且还可以包含其他导航字段，例如 groups、pages、icon，或指向外部页面的链接。
{
"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 和外部链接。
{
"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，或指向外部页面的链接。
{
"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"
}
]
}
}
{
"navigation": {
"global": {
"anchors": [
{
"anchor": "更新日志",
"icon": "list",
"href": "/changelog"
},
{
"anchor": "博客",
"icon": "pencil",
"href": "https://mintlify.com/blog"
}
]
},
"tabs": /*...*/
}
}
在 navigation 对象中，dropdowns 是一个数组，其中每个条目都是一个对象，必须包含 dropdown 字段，并且可以包含其他导航字段，例如 groups、pages、icons，或指向外部页面的链接。
{
"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，或指向外部页面的链接。
{
"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"
}
]
}
}
当你在某个导航元素（例如 anchor、tab 或 group）上添加 openapi 属性且未指定任何页面时，Mintlify 会自动为 OpenAPI 规范中定义的 所有端点 生成页面。若要控制显示哪些端点，请在 pages 数组中显式列出所需的端点。
{
"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 字段，并且可包含任何其他导航相关字段。
{
"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 字段，并且可以包含任意其他导航字段，包括特定语言的横幅配置。
我们目前支持以下语言的本地化：
{
"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"]
}
]
}
]
}
}
{
"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"]
}
]
}
]
}
}
docs.json 中通过 styling 属性控制站点是否启用面包屑导航。
"styling": {
"eyebrows": "breadcrumbs"
}
docs.json 中使用 interaction 属性来控制用户与导航元素的交互方式。
当用户展开一个导航分组时，某些主题会自动跳转到该分组中的第一页。你可以使用 drilldown 选项覆盖主题的默认行为。
- 设为
true：在选择导航分组时强制自动跳转到第一页。
- 设为
false：不进行跳转，选择时仅展开或折叠分组。
- 留空不设置：使用主题的默认行为。
"interaction": {
"drilldown": true // 当用户展开下拉菜单时强制跳转到第一页
}
