导航 - Mintlify

docs.json 中的 navigation 属性用于控制文档的结构与信息层级。通过合理配置导航，你可以更好地组织内容，帮助用户迅速找到所需信息。在导航的根级选择一种主要的组织方式。确定主要方式后，你可以在其内部嵌套其他导航元素。

选择一种主要方式

选择与你希望访客在文档顶级部分之间移动的方式相匹配的组织方式。

方式	适用场景	示例
分组	你的文档适合放在一条线性的侧边栏中，且不需要第二种导航维度。	单个产品的 SDK 参考。
选项卡	你有面向同一受众的并列部分，例如指南、API 参考和更新日志。	单个产品的“Guides”、“API reference”和“SDKs”选项卡。
锚点	你希望始终展示少量顶级目标（外部或内部）的固定链接。	与文档并列的社区、状态页或“主页”链接。
下拉菜单	你有多个部分，但不足以专门使用选项卡，或者你想把它们收纳进一个菜单。	在“Product docs”、“API reference”和“Partner docs”之间切换。
产品	你在一个部署下维护多个不同产品的文档，且每个产品都有自己完整的站点。	一个为“Payments”、“Identity”和“Analytics”分别提供文档的平台。
版本	你并行发布同一份文档的多个版本。	同时维护 `v1` 和 `v2` 的 API 文档。
语言	你发布同一份文档的翻译版本。	一个产品的英文、西班牙文和日文文档。

选项卡、下拉菜单、锚点、版本、语言和产品都可以一起出现——选择最能代表你顶级层级的一种，并将其余部分嵌套在分组内。

页面

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

在 navigation 对象中，pages 是一个数组，其中每个条目都必须指向一个页面文件的路径。

{
  "navigation": {
    "pages": [
      "settings",
      "pages",
      "navigation",
      "themes",
      "custom-domain"
    ]
  }
}

分组

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

在 navigation 对象中，groups 是一个数组，其中每一项都是一个对象，每个对象都必须包含 group 字段和 pages 字段。icon、tag、root 和 expanded 字段是可选的。

{
  "navigation": {
    "groups": [
      {
        "group": "Getting started",
        "icon": "play",
        "pages": [
          "quickstart",
          {
            "group": "Editing",
            "expanded": false,
            "icon": "pencil",
            "pages": [
              "installation",
              "editor"
            ]
          }
        ]
      },
      {
        "group": "编写内容",
        "icon": "notebook-text",
        "tag": "NEW",
        "pages": [
          "writing-content/page",
          "writing-content/text"
        ]
      }
    ]
  }
}

根页面

使用 root 属性为某个分组指定主页面。当一个分组设置了根页面时，在侧边栏导航中点击该分组的标题会打开根页面。根页面适用于顶级分组和嵌套分组。

Example group with a root page

{
  "navigation": {
    "groups": [
      {
        "group": "API 页面",
        "root": "api-overview",
        "pages": [
          "api-reference/get",
          "api-reference/post",
          "api-reference/delete"
        ]
      }
    ]
  }
}

目录列表

当一个分组有根页面时，你可以在该页面上生成目录列表。目录列表会显示分组的子页面和嵌套分组，让用户能够概览该部分的内容。在分组、选项卡或顶级 navigation 对象上设置 directory 属性以启用目录列表。该属性接受三个值：

值	描述
`"accordion"`	以列表形式显示子页面
`"card"`	以水平卡片形式显示子页面
`"none"`	禁用目录列表（默认）

directory 的值会通过导航层级继承。如果你在父元素上设置了 directory 值，该值将应用于所有后代分组，除非被覆盖。

Enable accordion directory for a group

{
  "navigation": {
    "groups": [
      {
        "group": "API reference",
        "root": "api-overview",
        "directory": "accordion",
        "pages": [
          "api-reference/authentication",
          "api-reference/endpoints",
          "api-reference/errors"
        ]
      }
    ]
  }
}

Enable card directory for all groups

{
  "navigation": {
    "directory": "card",
    "groups": [
      {
        "group": "Guides",
        "root": "guides/overview",
        "pages": [
          "guides/quickstart",
          "guides/configuration"
        ]
      }
    ]
  }
}

目录列表仅在分组根页面上显示。如果一个分组没有 root 属性，则无法显示目录列表。

默认展开状态

使用 expanded 属性来控制导航侧边栏中嵌套分组的默认状态。

expanded: true：默认展开分组。
expanded: false 或省略：默认折叠分组。

expanded 属性只会影响嵌套分组——也就是分组中的分组。顶级分组始终展开，你无法折叠它们。

{
  "group": "开始使用",
  "pages": [
    "quickstart",
    {
      "group": "高级功能",
      "expanded": false,
      "pages": ["installation", "configuration"]
    }
  ]
}

选项卡

选项卡可为你的文档创建彼此独立的 URL 路径分区。它们会在文档顶部生成一条水平导航栏，方便用户在各个部分之间切换。

在 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"
      }
    ]
  }
}

全局锚点

使用全局锚点为需要在所有页面上显示的链接提供入口，而不受用户当前查看的导航部分影响。全局锚点特别适合用于链接到文档之外的资源（例如博客、社区论坛或支持门户），也可用于为重要的内部页面（例如更新日志或状态页）提供一致的访问入口。全局锚点同时支持指向外部的 URL，以及指向文档内页面的相对路径。

{
  "navigation": {
    "global":  {
      "anchors": [
        {
          "anchor": "更新日志",
          "icon": "list",
          "href": "/changelog"
        },
        {
          "anchor": "博客",
          "icon": "pencil",
          "href": "https://mintlify.com/blog"
        }
      ]
    },
    "tabs": /*...*/
  }
}

产品

“产品”用于在导航中创建专门的分区，以组织针对特定产品的文档。使用“产品”将文档中的不同产品、服务或重要功能集彼此区分开。在 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"
      }
    ]
  }
}

下拉菜单

下拉菜单位于侧边栏导航顶部，是一个可展开的菜单。下拉菜单中的每个项都会跳转到文档的某个部分。

在 navigation 对象中，dropdowns 是一个数组，其中每个条目都是一个对象，必须包含 dropdown 字段，并且可以包含其他导航字段，例如 groups、pages、icons，或指向外部页面的链接。

{
  "navigation": {
    "dropdowns": [
      {
        "dropdown": "Documentation",
        "icon": "book-open",
        "pages": [
          "quickstart",
          "development",
          "navigation"
        ]
      },
      {
        "dropdown": "API 参考",
        "icon": "square-terminal",
        "pages": [
          "api-reference/get",
          "api-reference/post",
          "api-reference/delete"
        ]
      },
      {
        "dropdown": "Blog",
        "href": "https://external-link.com/blog"
      }
    ]
  }
}

OpenAPI

将 OpenAPI 规范直接集成到导航结构中，以自动生成 API 文档。你可以创建专门的 API 部分，或将端点（endpoint）页面放入其他导航组件中。可以在导航层级的任意级别设置一个默认的 OpenAPI 规范。子元素将继承该规范，除非它们定义了自己的规范。

当你在某个导航元素（例如 anchor、tab 或 group）上添加 openapi 属性且未指定任何页面时，Mintlify 会自动为 OpenAPI 规范中定义的 所有端点 生成页面。若要控制显示哪些端点，请在 pages 数组中显式列出所需的端点。

有关在文档中引用 OpenAPI 端点的更多信息，请参阅 OpenAPI 设置。

{
  "navigation": {
    "groups": [
      {
        "group": "API 参考",
        "openapi": "/path/to/openapi-v1.json",
        "pages": [
          "overview",
          "authentication",
          "GET /users",
          "POST /users",
          {
            "group": "Products",
            "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"]
          }
        ]
      }
    ]
  }
}

默认版本

Mintlify 使用 versions 数组中的第一个版本作为默认版本。使用 default 字段可将其他版本指定为默认版本。

{
  "navigation": {
    "versions": [
      {
        "version": "1.0.0",
        "groups": [
          {
            "group": "入门",
            "pages": ["v1/overview", "v1/quickstart"]
          }
        ]
      },
      {
        "version": "2.0.0",
        "default": true,
        "groups": [
          {
            "group": "入门",
            "pages": ["v2/overview", "v2/quickstart"]
          }
        ]
      }
    ]
  }
}

版本标签

使用可选的 tag 字段，在版本选择器的下拉菜单中为各版本条目添加徽章标签。使用这些标签来突出显示特定版本，例如 “Latest”、“Recommended” 或 “Beta”。

{
  "navigation": {
    "versions": [
      {
        "version": "2026_03",
        "tag": "Latest",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["getting-started", "quickstart"]
          }
        ]
      },
      {
        "version": "2025_12",
        "tag": "Recommended",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["2025_12/getting-started", "2025_12/quickstart"]
          }
        ]
      },
      {
        "version": "2025_09",
        "tag": "Deprecated",
        "groups": [
          {
            "group": "Getting started",
            "pages": ["2025_09/getting-started", "2025_09/quickstart"]
          }
        ]
      }
    ]
  }
}

语言

将导航划分为不同语言。用户可以从下拉菜单中选择语言。

在 navigation 对象中，languages 是一个数组，其中每一项都是一个对象，必须包含 language 字段，并且可以包含任何其他导航字段，包括特定语言的横幅、页脚和导航栏配置。我们目前支持以下语言的本地化：

阿拉伯语 (ar)

加泰罗尼亚语 (ca)

捷克语 (cs)

中文 (cn)

中文 (zh-Hant)

荷兰语 (nl)

英语 (en)

芬兰语 (fi)

法语 (fr)

德语 (de)

希伯来语 (he)

印地语 (hi)

匈牙利语 (hu)

印度尼西亚语 (id)

意大利语 (it)

日语 (jp)

韩语 (ko)

拉脱维亚语 (lv)

挪威语 (no)

波兰语 (pl)

葡萄牙语 (pt-BR)

罗马尼亚语 (ro)

俄语 (ru)

西班牙语 (es)

瑞典语 (sv)

土耳其语 (tr)

乌克兰语 (uk)

乌兹别克语 (uz)

越南语 (vi)

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "banner": {
          "content": "🚀 Version 2.0 is now live! See our [changelog](/en/changelog) for details.",
          "dismissible": true
        },
        "footer": {
          "socials": {
            "x": "https://x.com/mintlify"
          },
          "links": [
            {
              "header": "Resources",
              "items": [
                { "label": "Documentation", "href": "/en/docs" },
                { "label": "Blog", "href": "https://mintlify.com/blog" }
              ]
            }
          ]
        },
        "navbar": {
          "links": [
            { "label": "Docs", "href": "/en/docs" }
          ],
          "primary": {
            "type": "button",
            "label": "Get Started",
            "href": "/en/quickstart"
          }
        },
        "groups": [
          {
            "group": "Getting started",
            "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
        },
        "footer": {
          "socials": {
            "x": "https://x.com/mintlify"
          },
          "links": [
            {
              "header": "Recursos",
              "items": [
                { "label": "Documentación", "href": "/es/docs" },
                { "label": "Blog", "href": "https://mintlify.com/blog" }
              ]
            }
          ]
        },
        "navbar": {
          "links": [
            { "label": "Documentación", "href": "/es/docs" }
          ],
          "primary": {
            "type": "button",
            "label": "Comenzar",
            "href": "/es/quickstart"
          }
        },
        "groups": [
          {
            "group": "Getting started",
            "pages": ["es/overview", "es/quickstart", "es/development"]
          }
        ]
      }
    ]
  }
}

如需自动翻译，设置自动化，让代理按计划运行或在仓库推送时触发。

嵌套

你可以将导航元素相互嵌套，以创建复杂的层级结构。你必须有一个根级父导航元素，例如 tabs、groups 或下拉菜单。你可以在主要导航结构中嵌套其他类型的导航元素。在导航层级结构的每一层中，每个导航元素只能包含一种类型的子元素。比如，一个 tab 可以包含锚点，锚点下面可以包含 groups，但一个 tab 不能在同一级同时包含锚点和 groups。

{
  "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"]
          }
        ]
      }
    ]
  }
}

{
  "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"
      }
    ]
  }
}

{
  "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"]
      }
    ]
  }
}

{
  "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"]
          }
        ]
      }
    ]
  }
}

{
  "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 属性控制站点上是否显示面包屑导航。

"styling": {
  "eyebrows": "breadcrumbs"
}

"styling": {
  "eyebrows": "section"
}

交互配置

在 docs.json 中使用 interaction 属性来控制用户与导航元素的交互方式。当用户展开一个导航分组时，某些主题会自动跳转到该分组中的第一页。你可以使用 drilldown 选项覆盖主题的默认行为。

设为 true：当用户选择导航分组时强制自动跳转到第一页。
设为 false：当用户选择导航分组时不进行跳转，仅展开或折叠分组。
留空不设置：使用主题的默认行为。

"interaction": {
  "drilldown": true  // 当用户展开下拉菜单时强制跳转到第一页
}

"interaction": {
  "drilldown": false // 从不跳转，仅展开或折叠该分组
}

​选择一种主要方式

​页面

​分组

​根页面

​目录列表

​默认展开状态

​选项卡

​菜单

​锚点

​全局锚点

​产品

​下拉菜单

​OpenAPI

​版本

​默认版本

​版本标签

​语言

阿拉伯语 (ar)

加泰罗尼亚语 (ca)

捷克语 (cs)

中文 (cn)

中文 (zh-Hant)

荷兰语 (nl)

英语 (en)

芬兰语 (fi)

法语 (fr)

德语 (de)

希伯来语 (he)

印地语 (hi)

匈牙利语 (hu)

印度尼西亚语 (id)

意大利语 (it)

日语 (jp)

韩语 (ko)

拉脱维亚语 (lv)

挪威语 (no)

波兰语 (pl)

葡萄牙语 (pt-BR)

罗马尼亚语 (ro)

俄语 (ru)

西班牙语 (es)

瑞典语 (sv)

土耳其语 (tr)

乌克兰语 (uk)

乌兹别克语 (uz)

越南语 (vi)

​嵌套

​面包屑导航

​交互配置

​为 groups 启用自动导航

选择一种主要方式

页面

分组

根页面

目录列表

默认展开状态

选项卡

菜单

锚点

全局锚点

产品

下拉菜单

OpenAPI

版本

默认版本

版本标签

语言

嵌套

面包屑导航

交互配置

为 groups 启用自动导航