导航 - Mintlify

docs.json 中的 navigation 属性用于控制文档的结构与信息层级。通过合理配置导航，你可以更好地组织内容，帮助用户快速找到所需信息。

页面

页面是最基础的导航单元。它们对应你文档中的 MDX 文件。

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

{
  "navigation": {
    "pages": [
      "设置",
      "页面",
      "导航",
      "主题",
      "自定义域"
    ]
  }
}

分组

使用分组将侧边栏导航组织成多个部分。分组可以相互嵌套、添加标签，并搭配图标展示样式。

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

{
  "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，即可让它在导航侧边栏中默认展开。这有助于突出重要部分，或提升关键内容的可发现性。

{
  "group": "快速上手",
  "expanded": true,
  "pages": ["快速上手", "安装"]
}

选项卡

选项卡可为文档创建相互独立的部分，并具备各自的 URL 路径。它们会在文档顶部生成一条水平导航栏，便于用户在不同部分之间切换。

在 navigation 对象中，tabs 是一个数组，其中每个项都是一个对象，必须包含 tab 字段，并可包含其他导航字段，例如分组、页面、图标或外部链接。

{
  "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 字段，并且可以包含其他导航字段，例如分组、页面、图标或指向外部页面的链接。

{
  "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 字段，并且可以包含其他导航字段，例如分组、页面、图标或指向外部页面的链接。

{
  "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 字段，且不能指向相对路径。全局锚点特别适用于链接到不属于你文档的资源，但这些资源应便于用户随时访问，例如博客或支持门户。

{
  "navigation": {
    "global":  {
      "anchors": [
        {
          "anchor": "社区",
          "icon": "house",
          "href": "https://slack.com"
        },
        {
          "anchor": "博客",
          "icon": "pencil",
          "href": "https://mintlify.com/blog"
        }
      ]
    },
    "tabs": /*...*/
  }
}

下拉菜单

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

在 navigation 对象中，dropdowns 是一个数组，每个元素都是一个对象，必须包含 dropdown 字段，并且可以包含其他导航字段，例如分组、页面、图标或外部链接。

{
  "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规范。子元素将继承该规范，除非它们定义了自己的规范。

{
  "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 设置。

版本

将导航拆分为不同版本。可从下拉菜单中进行选择。

在 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 字段，并且可以包含任意其他导航字段。我们目前支持以下本地化语言：

Arabic (ar)

Chinese (cn)

Chinese (zh-Hant)

English (en)

French (fr)

German (de)

Indonesian (id)

Italian (it)

Japanese (jp)

Korean (ko)

Portuguese (pt-BR)

Russian (ru)

Spanish (es)

Turkish (tr)

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

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

嵌套

您可以任意组合使用锚点、标签页和下拉菜单。组件可以灵活相互嵌套，以构建所需的导航结构。

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

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

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

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

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

交互配置

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

设为 true：在选择导航分组时强制跳转到第一个页面。
设为 false：不进行跳转，只在选择时展开或收起该分组。
不设置：使用主题的默认行为。

"interaction": {
  "drilldown": true  // 当用户展开分组时，强制跳转到第一个页面
}

"interaction": {
  "drilldown": false // 从不跳转，只展开或收起该分组
}

快速入门

核心配置

AI 优化

组件

API 页面

认证与个性化

指南

集成

版本控制与CI/CD

导航

页面

分组

默认展开状态

选项卡

菜单

锚点

下拉菜单

OpenAPI

版本

语言

Arabic (ar)

Chinese (cn)

Chinese (zh-Hant)

English (en)

French (fr)

German (de)

Indonesian (id)

Italian (it)

Japanese (jp)

Korean (ko)

Portuguese (pt-BR)

Russian (ru)

Spanish (es)

Turkish (tr)

嵌套

交互配置

为分组启用自动导航

​页面

​分组

​默认展开状态

​选项卡

​菜单

​锚点

​下拉菜单

​OpenAPI

​版本

​语言

Arabic (ar)

Chinese (cn)

Chinese (zh-Hant)

English (en)

French (fr)

German (de)

Indonesian (id)

Italian (it)

Japanese (jp)

Korean (ko)

Portuguese (pt-BR)

Russian (ru)

Spanish (es)

Turkish (tr)

​嵌套

​面包屑导航

​交互配置

​为分组启用自动导航

页面

分组

默认展开状态

选项卡

菜单

锚点

下拉菜单

OpenAPI

版本

语言

嵌套

面包屑导航

交互配置

为分组启用自动导航