导航

设计契合用户需求的信息架构。

docs.json 中的 navigation 属性用于控制文档的结构与信息层级。

通过合理配置导航，你可以更好地组织内容，帮助用户迅速找到所需信息。

在导航的根级选择一种主要的组织方式。确定主要方式后，你可以在其内部嵌套其他导航元素。

​

页面

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

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

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

​

分组

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

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

​

选项卡

选项卡可为你的文档创建彼此独立的 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 的 href 字段，且不能包含相对路径。

{
  "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，或指向外部页面的链接。

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

​

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": [
          "概述",
          "认证",
          "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 字段，并且可以包含任意其他导航字段。

我们目前支持以下语言的本地化：

阿拉伯语（ar）

中文（cn）

中文（zh-Hant）

荷兰语（nl）

英语（en）

法语（fr）

德语（de）

印尼语（id）

意大利语（it）

日语（jp）

韩语（ko）

拉脱维亚语（lv）

挪威语（no）

葡萄牙语（pt-BR）

俄语（ru）

西班牙语（es）

瑞典语（sv）

土耳其语（tr）

乌克兰语（ua）

越南语（vn）

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "groups": [
          {
            "group": "快速入门",
            "pages": ["en/overview", "en/quickstart", "en/development"]
          }
        ]
      },
      {
        "language": "es",
        "groups": [
          {
            "group": "快速入门",
            "pages": ["es/overview", "es/quickstart", "es/development"]
          }
        ]
      }
    ]
  }
}

如需自动翻译，请联系我们的销售团队讨论解决方案。

​

嵌套

导航元素可以相互嵌套，以创建复杂的层级结构。你必须有一个根级父导航元素，例如 tabs、groups 或下拉菜单。你可以在主要导航结构中嵌套其他类型的导航元素。

在导航层级结构的每一层中，每个导航元素只能包含一种类型的子元素。比如，一个 tab 可以包含锚点，锚点下面可以包含 groups，但一个 tab 不能在同一级同时包含锚点和 groups。

包含锚点的 Tabs

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

Display full breadcrumbs

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

​

交互配置

在 docs.json 中使用 interaction 属性来控制用户与导航元素的交互方式。

​

为 groups 启用自动导航

当用户展开一个导航分组时，某些主题会自动跳转到该分组中的第一页。你可以使用 drilldown 选项覆盖主题的默认行为。

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

强制导航

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