> ## Documentation Index
> Fetch the complete documentation index at: https://omer-914cc1c6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 全局设置

> 使用 `docs.json` 文件配置全站设置

`docs.json` 文件可将一组 Markdown 文件构建成可导航、可自定义的文档站点。这个必需的配置文件控制样式、navigation、integrations 等设置，是你的文档的蓝图。

`docs.json` 中的设置会全局作用于所有页面。

<div id="setting-up-your-docsjson">
  ## 配置你的 `docs.json`
</div>

开始时，你只需指定 `theme`、`name`、`colors.primary` 和 `navigation`。其他字段是可选的，可随着文档需求的增长逐步添加。

为获得最佳编辑体验，请在 `docs.json` 文件开头加入模式（schema）引用。这样可在大多数代码编辑器中启用自动补全、校验和实用的悬浮提示：

```json theme={null}
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "您的文档",
  "colors": {
    "primary": "#ff0000"
  },
  "navigation": {
    // 您的导航结构
  }
  // 配置的其余部分
}
```

<div id="reference">
  ## 参考
</div>

本节提供 `docs.json` 文件的完整参考资料。

<div id="customization">
  ### 自定义
</div>

<ResponseField name="theme" required>
  站点的布局主题。

  以下之一：`mint`、`maple`、`palm`、`willow`、`linden`、`almond`、`aspen`。

  更多信息请参阅 [Themes](zh/themes)。
</ResponseField>

<ResponseField name="name" type="string" required>
  您的项目、组织或产品名称。
</ResponseField>

<ResponseField name="colors" type="object" required>
  文档中使用的配色。不同主题的应用方式不同。若仅提供主色，将用于所有相关颜色元素。

  <Expandable title="Colors">
    <ResponseField name="primary" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$" required>
      文档的主色。通常在浅色模式下用于强调，具体因主题而异。

      必须是以 `#` 开头的十六进制色值。
    </ResponseField>

    <ResponseField name="light" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
      深色模式下用于强调的颜色。

      必须是以 `#` 开头的十六进制色值。
    </ResponseField>

    <ResponseField name="dark" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
      在浅色与深色模式下用于按钮和悬停状态的颜色，具体因主题而异。

      必须是以 `#` 开头的十六进制色值。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="description" type="string">
  用于 SEO（搜索引擎优化）和 AI 索引编入的站点说明。
</ResponseField>

<ResponseField name="logo" type="string or object">
  适用于浅色和深色模式的徽标。

  <Expandable title="Logo">
    <ResponseField name="light" type="string" required>
      指向浅色模式徽标文件的路径。需包含文件扩展名。示例：`/logo.png`
    </ResponseField>

    <ResponseField name="dark" type="string" required>
      指向深色模式徽标文件的路径。需包含文件扩展名。示例：`/logo-dark.png`
    </ResponseField>

    <ResponseField name="href" type="string (uri)">
      点击徽标时跳转的 URL。若未提供，徽标将链接到您的首页。示例：`https://mintlify.com`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="favicon" type="string or object">
  指向 favicon 文件的路径，需包含文件扩展名。会自动调整为合适的 favicon 尺寸。
  可为单个文件，或分别为浅色与深色模式提供文件。示例：`/favicon.png`

  <Expandable title="Favicon">
    <ResponseField name="light" type="string" required>
      指向浅色模式 favicon 文件的路径。需包含文件扩展名。示例：`/favicon.png`
    </ResponseField>

    <ResponseField name="dark" type="string" required>
      指向深色模式 favicon 文件的路径。需包含文件扩展名。示例：`/favicon-dark.png`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="thumbnails" type="object">
  用于社交媒体与页面预览的缩略图自定义。

  <Expandable title="Thumbnails">
    <ResponseField name="appearance" type="&#x22;light&#x22; | &#x22;dark&#x22;">
      缩略图的视觉主题。若未指定，将使用由 `colors` 字段定义的站点配色方案。
    </ResponseField>

    <ResponseField name="background" type="string">
      缩略图的背景图像。可为相对路径或绝对 URL。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="styling" type="object">
  视觉样式配置。

  <Expandable title="Styling">
    <ResponseField name="eyebrows" type="&#x22;section&#x22; | &#x22;breadcrumbs&#x22;">
      页面眉的样式。选择 `section` 显示分区名称，或选择 `breadcrumbs` 显示完整导航路径。默认为 `section`。
    </ResponseField>

    <ResponseField name="codeblocks" type="&#x22;system&#x22; | &#x22;dark&#x22;">
      代码块的主题。选择 `system` 以匹配站点主题，或选择 `dark` 始终使用深色代码块。默认为 `system`。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="icons" type="object">
  图标库设置。

  <Expandable title="Icons">
    <ResponseField name="library" type="&#x22;fontawesome&#x22; | &#x22;lucide&#x22;" required>
      在整站文档中使用的图标库。默认为 `fontawesome`。

      <Note>
        无论库设置如何，你都可以为任意单个图标指定外部托管图标的 URL、项目中图标文件的路径，或兼容 JSX 的 SVG 代码。
      </Note>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="fonts" type="object">
  文档的字体配置。默认字体为 [Inter](https://fonts.google.com/specimen/Inter)。

  <Expandable title="Fonts">
    <ResponseField name="family" type="string" required>
      字体系列，例如 “Open Sans”。
    </ResponseField>

    <ResponseField name="weight" type="number">
      字重，例如 400 或 700。可变字体支持更精确的字重，例如 550。
    </ResponseField>

    <ResponseField name="source" type="string (uri)">
      字体来源的 URL，例如 [https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2。](https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2。) 当你指定 Google 字体的 `family` 名称时，[Google Fonts](https://fonts.google.com) 会自动加载，因此无需提供来源 URL。
    </ResponseField>

    <ResponseField name="format" type="&#x22;woff&#x22; | &#x22;woff2&#x22;">
      字体文件格式。
    </ResponseField>

    <ResponseField name="heading" type="object">
      专用于标题的字体覆盖设置。

      <Expandable title="Heading">
        <ResponseField name="family" type="string" required>
          字体系列，例如 “Open Sans”“Playfair Display”。
        </ResponseField>

        <ResponseField name="weight" type="number">
          字重，例如 400、700。可变字体支持更精确的字重，例如 550。
        </ResponseField>

        <ResponseField name="source" type="string (uri)">
          字体来源的 URL，例如 [https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2。](https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2。) 当你指定 Google 字体的 `family` 名称时，[Google Fonts](https://fonts.google.com) 会自动加载，因此无需提供来源 URL。
        </ResponseField>

        <ResponseField name="format" type="&#x22;woff&#x22; | &#x22;woff2&#x22;">
          字体文件格式。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="body" type="object">
      专用于正文的字体覆盖设置。

      <Expandable title="Body">
        <ResponseField name="family" type="string" required>
          字体系列，例如 “Open Sans”“Playfair Display”。
        </ResponseField>

        <ResponseField name="weight" type="number">
          字重，例如 400、700。可变字体支持更精确的字重，例如 550。
        </ResponseField>

        <ResponseField name="source" type="string (uri)">
          字体来源的 URL，例如 [https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2。](https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2。) 当你指定 Google 字体的 `family` 名称时，[Google Fonts](https://fonts.google.com) 会自动加载，因此无需提供来源 URL。
        </ResponseField>

        <ResponseField name="format" type="&#x22;woff&#x22; | &#x22;woff2&#x22;">
          字体文件格式。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="appearance" type="object">
  明暗模式切换设置。

  <Expandable title="Appearance">
    <ResponseField name="default" type="&#x22;system&#x22; | &#x22;light&#x22; | &#x22;dark&#x22;">
      默认主题模式。选择 `system` 以匹配用户的操作系统设置，或选择 `light` 或 `dark` 以强制使用特定模式。默认为 `system`。
    </ResponseField>

    <ResponseField name="strict" type="boolean">
      是否隐藏明暗模式切换。默认为 `true`。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="background" type="object">
  背景颜色与装饰的设置。

  <Expandable title="Background">
    <ResponseField name="image" type="string or object">
      站点的背景图片。可为单个文件，或分别为浅色与深色模式提供不同文件。

      <Expandable title="Image">
        <ResponseField name="light" type="string" required>
          浅色模式的背景图片路径。需包含文件扩展名。示例：`/background.png`。
        </ResponseField>

        <ResponseField name="dark" type="string" required>
          深色模式的背景图片路径。需包含文件扩展名。示例：`/background-dark.png`。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="decoration" type="&#x22;gradient&#x22; | &#x22;grid&#x22; | &#x22;windows&#x22;">
      主题的背景装饰效果。
    </ResponseField>

    <ResponseField name="color" type="object">
      为浅色与深色模式自定义背景颜色。

      <Expandable title="Color">
        <ResponseField name="light" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
          浅色模式的背景颜色。

          必须是以 `#` 开头的十六进制色值。
        </ResponseField>

        <ResponseField name="dark" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
          深色模式的背景颜色。

          必须是以 `#` 开头的十六进制色值。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<div id="structure">
  ### 结构
</div>

<ResponseField name="navbar" type="object">
  指向外部链接的导航栏条目。

  <Expandable title="Navbar">
    <ResponseField name="links" type="array of object">
      要在导航栏中显示的链接

      <Expandable title="Links">
        <ResponseField name="label" type="string" required>
          链接文本。
        </ResponseField>

        <ResponseField name="href" type="string (uri)" required>
          链接目标。必须是有效的外部 URL。
        </ResponseField>

        <ResponseField name="icon" type="string">
          要显示的 icon。

          选项：

          * [Font Awesome icon](https://fontawesome.com/icons) 名称
          * [Lucide icon](https://lucide.dev/icons) 名称
          * 用花括号包裹的 JSX 兼容 SVG 代码
          * 指向外部托管 icon 的 URL
          * 项目中 icon 文件的路径

          针对自定义 SVG icon：

          1. 使用 [SVGR 转换器](https://react-svgr.com/playground/)将你的 SVG 转换为 JSX。
          2. 将 SVG 代码粘贴到 SVG 输入框。
          3. 从 JSX 输出框中复制完整的 `<svg>...</svg>` 元素。
          4. 用花括号包裹 JSX 兼容的 SVG 代码：`icon={<svg ...> ... </svg>}`。
          5. 按需调整 `height` 和 `width`。
        </ResponseField>

        <ResponseField name="iconType" type="string">
          [Font Awesome](https://fontawesome.com/icons) icon 的样式。仅在使用 Font Awesome icon 时生效。

          选项：`regular`、`solid`、`light`、`thin`、`sharp-solid`、`duotone`、`brands`。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="primary" type="object">
      导航栏中的主按钮。

      <Expandable title="Primary">
        <ResponseField name="type" type="&#x22;button&#x22; | &#x22;github&#x22;" required>
          按钮样式。选择 `button` 表示带有文本的标准按钮；选择 `github` 表示指向 GitHub 存储库并带有 icon 的链接。
        </ResponseField>

        <ResponseField name="label" type="string" required>
          按钮文本。仅当 `type` 为 `button` 时生效。
        </ResponseField>

        <ResponseField name="href" type="string (uri)" required>
          按钮目标。必须是外部 URL。若 `type` 为 `github`，则必须是 GitHub 存储库的 URL。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="导航" type="object" required>
  您内容的导航结构。

  <Expandable title="导航">
    <ResponseField name="全局" type="object">
      在所有页面和章节中显示的全局导航元素。

      <Expandable title="全局">
        <ResponseField name="语言" type="array of object">
          本地化站点的语言切换配置。

          <Expandable title="Languages">
            <ResponseField name="language" type="&#x22;en&#x22; | &#x22;cn&#x22; | &#x22;zh&#x22; | &#x22;zh-Hans&#x22; | &#x22;zh-Hant&#x22; | &#x22;es&#x22; | &#x22;fr&#x22; | &#x22;ja&#x22; | &#x22;jp&#x22; | &#x22;pt&#x22; | &#x22;pt-BR&#x22; | &#x22;de&#x22; | &#x22;ko&#x22; | &#x22;it&#x22; | &#x22;ru&#x22; | &#x22;id&#x22; | &#x22;ar&#x22; | &#x22;tr&#x22;" required>
              符合 ISO 639-1 的语言代码
            </ResponseField>

            <ResponseField name="default" type="boolean">
              是否为默认语言。
            </ResponseField>

            <ResponseField name="hidden" type="boolean">
              是否默认隐藏此语言选项。
            </ResponseField>

            <ResponseField name="href" type="string (uri)" required>
              指向该语言文档版本的有效路径或外部链接。
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="版本" type="array of object">
          用于多版本站点的版本切换器配置。

          <Expandable title="Versions">
            <ResponseField name="version" type="string" required>
              版本的显示名称。

              最小长度：1
            </ResponseField>

            <ResponseField name="default" type="boolean">
              是否为默认版本。
            </ResponseField>

            <ResponseField name="hidden" type="boolean">
              是否默认隐藏该版本选项。
            </ResponseField>

            <ResponseField name="href" type="string (uri)" required>
              指向该文档版本的 URL 或路径。
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="Tabs" type="array of object">
          用于组织主要版块的顶层导航选项卡。

          <Expandable title="Tabs">
            <ResponseField name="tab" type="string" required>
              标签页的显示名称。

              最小长度：1
            </ResponseField>

            <ResponseField name="icon" type="string">
              要显示的 icon。

              选项：

              * [Font Awesome icon](https://fontawesome.com/icons) 名称
              * [Lucide icon](https://lucide.dev/icons) 名称
              * 用花括号包裹的 JSX 兼容 SVG 代码
              * 指向外部托管 icon 的 URL
              * 项目中 icon 文件的路径

              针对自定义 SVG icon：

              1. 使用 [SVGR 转换器](https://react-svgr.com/playground/)将你的 SVG 转换为 JSX。
              2. 将 SVG 代码粘贴到 SVG 输入框。
              3. 从 JSX 输出框中复制完整的 `<svg>...</svg>` 元素。
              4. 用花括号包裹 JSX 兼容的 SVG 代码：`icon={<svg ...> ... </svg>}`。
              5. 按需调整 `height` 和 `width`。
            </ResponseField>

            <ResponseField name="iconType" type="string">
              [Font Awesome](https://fontawesome.com/icons) icon 的样式。仅在使用 Font Awesome icon 时生效。

              选项：`regular`、`solid`、`light`、`thin`、`sharp-solid`、`duotone`、`brands`。
            </ResponseField>

            <ResponseField name="hidden" type="boolean">
              是否默认隐藏此标签页。
            </ResponseField>

            <ResponseField name="href" type="string (uri)" required>
              指向该标签页目标的 URL 或路径。
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="锚点" type="array of object">
          在侧边栏导航中醒目显示的锚点链接。

          <Expandable title="Anchors">
            <ResponseField name="anchor" type="string" required>
              锚点的显示名称。

              最小长度：1
            </ResponseField>

            <ResponseField name="icon" type="string">
              要显示的 icon。

              选项：

              * [Font Awesome icon](https://fontawesome.com/icons) 名称
              * [Lucide icon](https://lucide.dev/icons) 名称
              * 用花括号包裹的 JSX 兼容 SVG 代码
              * 指向外部托管 icon 的 URL
              * 项目中 icon 文件的路径

              针对自定义 SVG icon：

              1. 使用 [SVGR 转换器](https://react-svgr.com/playground/)将你的 SVG 转换为 JSX。
              2. 将 SVG 代码粘贴到 SVG 输入框。
              3. 从 JSX 输出框中复制完整的 `<svg>...</svg>` 元素。
              4. 用花括号包裹 JSX 兼容的 SVG 代码：`icon={<svg ...> ... </svg>}`。
              5. 按需调整 `height` 和 `width`。
            </ResponseField>

            <ResponseField name="iconType" type="string">
              [Font Awesome](https://fontawesome.com/icons) icon 的样式。仅在使用 Font Awesome icon 时生效。

              选项：`regular`、`solid`、`light`、`thin`、`sharp-solid`、`duotone`、`brands`。
            </ResponseField>

            <ResponseField name="color" type="object">
              锚点的自定义颜色。

              <Expandable title="Color">
                <ResponseField name="light" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
                  浅色模式下的锚点颜色。

                  必须是以 `#` 开头的十六进制色值。
                </ResponseField>

                <ResponseField name="dark" type="string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$">
                  深色模式下的锚点颜色。

                  必须是以 `#` 开头的十六进制色值。
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="hidden" type="boolean">
              是否默认隐藏此锚点。
            </ResponseField>

            <ResponseField name="href" type="string (uri)" required>
              指向锚点目标的 URL 或路径。
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="下拉菜单" type="array of object">
          用于组织相关内容的下拉菜单。

          <Expandable title="Dropdowns">
            <ResponseField name="dropdown" type="string" required>
              下拉菜单的显示名称。

              最小长度：1
            </ResponseField>

            <ResponseField name="icon" type="string">
              要显示的 icon。

              选项：

              * [Font Awesome icon](https://fontawesome.com/icons) 名称
              * [Lucide icon](https://lucide.dev/icons) 名称
              * 用花括号包裹的 JSX 兼容 SVG 代码
              * 指向外部托管 icon 的 URL
              * 项目中 icon 文件的路径

              针对自定义 SVG icon：

              1. 使用 [SVGR 转换器](https://react-svgr.com/playground/)将你的 SVG 转换为 JSX。
              2. 将 SVG 代码粘贴到 SVG 输入框。
              3. 从 JSX 输出框中复制完整的 `<svg>...</svg>` 元素。
              4. 用花括号包裹 JSX 兼容的 SVG 代码：`icon={<svg ...> ... </svg>}`。
              5. 按需调整 `height` 和 `width`。
            </ResponseField>

            <ResponseField name="iconType" type="string">
              [Font Awesome](https://fontawesome.com/icons) icon 的样式。仅在使用 Font Awesome icon 时生效。

              选项：`regular`、`solid`、`light`、`thin`、`sharp-solid`、`duotone`、`brands`。
            </ResponseField>

            <ResponseField name="hidden" type="boolean">
              是否默认隐藏该下拉菜单。
            </ResponseField>

            <ResponseField name="href" type="string (uri)" required>
              下拉菜单目标的 URL 或路径。
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="语言" type="array of object">
      适用于[多语言](zh/navigation#languages)站点的语言切换器。
    </ResponseField>

    <ResponseField name="版本" type="array of object">
      为拥有多个[版本](zh/navigation#versions)的网站提供版本切换器。
    </ResponseField>

    <ResponseField name="Tabs" type="array of object">
      顶层导航的 [tabs](zh/navigation#tabs)。
    </ResponseField>

    <ResponseField name="锚点" type="array of object">
      侧边栏[锚点](zh/navigation#anchors)。
    </ResponseField>

    <ResponseField name="下拉菜单" type="array of object">
      [下拉菜单](zh/navigation#dropdowns)，用于分组相关内容。
    </ResponseField>

    <ResponseField name="groups" type="array of object">
      [Groups](zh/navigation#groups) 用于将内容组织成各个部分。
    </ResponseField>

    <ResponseField name="页面" type="array of string or object">
      构成文档的各个[页面](zh/navigation#pages)。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="interaction" type="object">
  导航元素的用户交互设置。

  <Expandable title="Interaction">
    <ResponseField name="drilldown" type="boolean">
      控制选择导航分组时的自动导航行为。设为 `true` 时，在展开导航分组时强制进入第一篇页面。设为 `false` 时不跳转，仅展开或折叠该分组。留空则使用主题的默认行为。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="footer" type="object">
  页脚内容与社交媒体链接。

  <Expandable title="Footer">
    <ResponseField name="socials" type="object">
      要在页脚中显示的社交媒体帐号。每个 key 为平台名称，每个 value 为你的个人资料 URL。例如：

      ```json theme={null}
      {
        "x": "https://x.com/mintlify"
      }
      ```

      可用的属性名称：`x`、`website`、`facebook`、`youtube`、`discord`、`slack`、`github`、`linkedin`、`instagram`、`hacker-news`、`medium`、`telegram`、`twitter`、`x-twitter`、`earth-americas`、`bluesky`、`threads`、`reddit`、`podcast`
    </ResponseField>

    <ResponseField name="links" type="array of object">
      要在页脚中显示的链接。

      <Expandable title="Links">
        <ResponseField name="header" type="string">
          列标题。

          最小长度：1
        </ResponseField>

        <ResponseField name="items" type="array of object" required>
          要在该列中显示的链接。

          <Expandable title="Items">
            <ResponseField name="label" type="string" required>
              链接文本。

              最小长度：1
            </ResponseField>

            <ResponseField name="href" type="string (uri)" required>
              链接目标 URL。
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="banner" type="object">
  显示在页面顶部的全站横幅。

  <Expandable title="Banner">
    <ResponseField name="content" type="string">
      横幅内容。支持纯文本和 Markdown 格式。例如：

      ```json theme={null}
      {
        "content": "🚀 Banner is live! [Learn more](mintlify.com)"
      }
      ```
    </ResponseField>

    <ResponseField name="dismissible" type="boolean">
      用户是否可以关闭横幅。默认为 `false`。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="redirects" type="array of object">
  针对页面移动、重命名或删除的重定向。

  <Expandable title="Redirects">
    <ResponseField name="source" type="string" required>
      要从中重定向的源路径。示例：`/old-page`
    </ResponseField>

    <ResponseField name="destination" type="string" required>
      要重定向到的目标路径。示例：`/new-page`
    </ResponseField>

    <ResponseField name="permanent" type="boolean">
      是否使用永久重定向（301）。默认为 `true`。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="contextual" type="object">
  用于 AI 优化内容和集成的上下文菜单。

  <Expandable title="Contextual">
    <ResponseField name="options" type="array of &#x22;copy&#x22; | &#x22;view&#x22; | &#x22;chatgpt&#x22; | &#x22;claude&#x22; | &#x22;perplexity&#x22; | &#x22;mcp&#x22; | &#x22;cursor&#x22; | &#x22;vscode&#x22;" required>
      上下文菜单中的可用操作。第一个选项将作为默认项显示。

      * `copy`：将当前页面以 Markdown 形式复制到剪贴板。
      * `view`：在新标签页中以 Markdown 查看当前页面。
      * `chatgpt`：将当前页面内容发送到 ChatGPT。
      * `claude`：将当前页面内容发送到 Claude。
      * `perplexity`：将当前页面内容发送到 Perplexity。
      * `mcp`：将你的 MCP 服务器 URL 复制到剪贴板。
      * `cursor`：在 Cursor 中安装你托管的 MCP 服务器。
      * `vscode`：在 VSCode 中安装你托管的 MCP 服务器。

      <img src="https://mintcdn.com/omer-914cc1c6/zyJsbuZtXQKHf9Ui/images/page-context-menu.png?fit=max&auto=format&n=zyJsbuZtXQKHf9Ui&q=85&s=7661edd9902d6a4b1d105ebc72a0ddbe" alt="Contextual Menu" className="rounded-xl" width="1348" height="824" data-path="images/page-context-menu.png" />

      <Note>
        上下文菜单仅在预览和生产部署中可用。
      </Note>
    </ResponseField>
  </Expandable>
</ResponseField>

<div id="api-configurations">
  ### API 配置
</div>

<ResponseField name="api" type="object">
  API 文档与交互式操作台的相关设置。

  <Expandable title="Api">
    <ResponseField name="openapi" type="string or array or object">
      用于生成 API 文档的 OpenAPI 规范文件。可为单个 URL/路径，也可为多个 URL/路径组成的数组。

      <Expandable title="Openapi">
        <ResponseField name="source" type="string">
          OpenAPI 规范文件的 URL 或路径。

          最小长度：1
        </ResponseField>

        <ResponseField name="directory" type="string">
          用于搜索 OpenAPI 文件的目录。

          请勿以斜杠开头。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="asyncapi" type="string or array or object">
      用于生成 API 文档的 AsyncAPI 规范文件。可为单个 URL/路径，也可为多个 URL/路径组成的数组。

      <Expandable title="Asyncapi">
        <ResponseField name="source" type="string">
          AsyncAPI 规范文件的 URL 或路径。

          最小长度：1
        </ResponseField>

        <ResponseField name="directory" type="string">
          用于搜索 AsyncAPI 文件的目录。

          请勿以斜杠开头。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="params" type="object">
      API 参数的显示设置。

      <Expandable title="Params">
        <ResponseField name="expanded" type="&#x22;all&#x22; | &#x22;closed&#x22;">
          是否默认展开所有参数。默认值为 `closed`。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="playground" type="object">
      API 操作台设置。

      <Expandable title="Playground">
        <ResponseField name="display" type="&#x22;interactive&#x22; | &#x22;simple&#x22; | &#x22;none&#x22;">
          API 操作台的显示模式。默认值为 `interactive`。
        </ResponseField>

        <ResponseField name="proxy" type="boolean">
          是否通过代理服务器转发 API 请求。默认值为 `true`。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="examples" type="object">
      自动生成的 API 示例配置。

      <Expandable title="Examples">
        <ResponseField name="languages" type="array of string">
          自动生成的 API 代码片段的示例语言。
        </ResponseField>

        <ResponseField name="defaults" type="&#x22;required&#x22; | &#x22;all&#x22;">
          是否在 API 示例中显示可选参数。默认值为 `all`。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="mdx" type="object">
      基于 `MDX` 文件生成的 API 页面配置。

      <Expandable title="Mdx">
        <ResponseField name="auth" type="object">
          基于 MDX 的 API 请求的认证配置。

          <Expandable title="Auth">
            <ResponseField name="method" type="&#x22;bearer&#x22; | &#x22;basic&#x22; | &#x22;key&#x22; | &#x22;cobo&#x22;">
              API 请求的认证方式。
            </ResponseField>

            <ResponseField name="name" type="string">
              API 请求的认证名称。
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="server" type="string or array">
          API 请求的服务器配置。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<div id="seo-and-search">
  ### SEO 与搜索
</div>

<ResponseField name="seo" type="object">
  SEO（搜索引擎优化）索引配置。

  <Expandable title="Seo">
    <ResponseField name="metatags" type="object">
      添加到每个页面的 Meta 标签。必须是有效的 key-value 键值对。可在 [常用 Meta 标签参考](/zh/settings/seo#common-meta-tags-reference) 中查看可选项。
    </ResponseField>

    <ResponseField name="indexing" type="&#x22;navigable&#x22; | &#x22;all&#x22;">
      指定哪些页面应被搜索引擎收录。选择 `navigable` 仅收录 `docs.json` 的 navigation 中的页面，选择 `all` 则收录所有页面。默认值为 `navigable`。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="search" type="object">
  搜索展示设置。

  <Expandable title="Search">
    <ResponseField name="prompt" type="string">
      搜索栏的占位提示文本。
    </ResponseField>
  </Expandable>
</ResponseField>

<div id="integrations">
  ### 集成
</div>

<ResponseField name="集成" type="object">
  第三方集成。

  <Expandable title="集成">
    <ResponseField name="Amplitude" type="object">
      Amplitude Analytics 集成。

      <Expandable title="Amplitude">
        <ResponseField name="apiKey" type="string" required>
          您的 Amplitude API 密钥。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Clearbit" type="object">
      Clearbit 数据富集集成。

      <Expandable title="Clearbit">
        <ResponseField name="publicApiKey" type="string" required>
          您的 Clearbit API key。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Fathom" type="object">
      Fathom Analytics 集成。

      <Expandable title="Fathom">
        <ResponseField name="siteId" type="string" required>
          您的 Fathom 站点 ID。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Frontchat" type="object">
      Front 聊天集成。

      <Expandable title="Frontchat">
        <ResponseField name="snippetId" type="string" required>
          你的 Front 聊天代码片段 ID。

          最小长度：6
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="GA4" type="object">
      Google Analytics 4 集成。

      <Expandable title="Ga4">
        <ResponseField name="measurementId" type="string matching ^G" required>
          您的 Google Analytics 4 measurement ID。

          必须符合模式：^G
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="GTM（Google Tag Manager）" type="object">
      Google Tag Manager 集成。

      <Expandable title="Gtm">
        <ResponseField name="tagId" type="string matching ^G" required>
          您的 Google Tag Manager 标签 ID。

          必须符合模式：^G
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Heap" type="object">
      Heap Analytics 集成。

      <Expandable title="Heap">
        <ResponseField name="appId" type="string" required>
          你的 Heap appId。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Hotjar" type="object">
      Hotjar 集成。

      <Expandable title="Hotjar">
        <ResponseField name="hjid" type="string" required>
          您的 Hotjar ID。
        </ResponseField>

        <ResponseField name="hjsv" type="string" required>
          您的 Hotjar 脚本版本。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Intercom" type="object">
      Intercom 集成。

      <Expandable title="Intercom">
        <ResponseField name="appId" type="string" required>
          您的 Intercom 应用 ID。

          最小长度：6
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Koala" type="object">
      Koala 集成。

      <Expandable title="Koala">
        <ResponseField name="publicApiKey" type="string" required>
          您的 Koala 公共 API key。

          最小长度：2
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="LogRocket" type="object">
      LogRocket 集成。

      <Expandable title="LogRocket">
        <ResponseField name="appId" type="string" required>
          您的 LogRocket 应用 ID。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Mixpanel" type="object">
      Mixpanel 集成。

      <Expandable title="Mixpanel">
        <ResponseField name="projectToken" type="string" required>
          您的 Mixpanel 项目令牌。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Osano" type="object">
      与 Osano 的集成。

      <Expandable title="Osano">
        <ResponseField name="scriptSource" type="string" required>
          您的 Osano 脚本地址。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Pirsch" type="object">
      Pirsch Analytics 集成。

      <Expandable title="Pirsch">
        <ResponseField name="id" type="string" required>
          你的 Pirsch ID。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="PostHog" type="object">
      PostHog 集成。

      <Expandable title="Posthog">
        <ResponseField name="apiKey" type="string matching ^phc\_" required>
          你的 PostHog API key。

          必须匹配模式：^phc\_
        </ResponseField>

        <ResponseField name="apiHost" type="string (uri)">
          你的 PostHog API 主机地址。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Plausible" type="object">
      Plausible Analytics 集成。

      <Expandable title="Plausible">
        <ResponseField name="domain" type="string" required>
          你的 Plausible domain（域名）。
        </ResponseField>

        <ResponseField name="server" type="string">
          你的 Plausible 服务器地址。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Segment" type="object">
      Segment 集成。

      <Expandable title="Segment">
        <ResponseField name="key" type="string" required>
          你的 Segment key。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="遥测/使用数据" type="object">
      遥测设置。

      <Expandable title="遥测">
        <ResponseField name="enabled" type="boolean">
          是否启用遥测。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="Cookie（浏览器 Cookie）" type="object">
      Cookie 设置。

      <Expandable title="Cookie">
        <ResponseField name="key" type="string">
          Cookie 的 key。
        </ResponseField>

        <ResponseField name="value" type="string">
          Cookie 的值。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<div id="errors">
  ### 错误
</div>

<ResponseField name="errors" type="object">
  错误处理设置。

  <Expandable title="Errors">
    <ResponseField name="404" type="object">
      404“页面未找到”错误的处理。

      <Expandable title="404">
        <ResponseField name="redirect" type="boolean">
          当页面未找到时是否自动重定向到首页。
        </ResponseField>

        <ResponseField name="title" type="string">
          404 错误页面的自定义标题。
        </ResponseField>

        <ResponseField name="description" type="string">
          404 错误页面的自定义说明。支持 Markdown 格式。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<div id="examples">
  ## 示例
</div>

<Tabs>
  <Tab title="基础示例">
    ```json title="docs.json" wrap lines theme={null}
    {
      "$schema": "https://mintlify.com/docs.json",
      "theme": "maple",
      "name": "Example Co.",
      "description": "Example Co. 是一家提供示例内容和占位符文本的公司。",
      "colors": {
        "primary": "#3B82F6",
        "light": "#F8FAFC",
        "dark": "#0F172A"
      },
      "navigation": {
        "dropdowns": [
          {
            "dropdown": "文档",
            "icon": "book",
            "description": "如何使用 Example Co. 产品",
            "groups": [
              {
                "group": "快速开始",
                "pages": [
                  "index",
                  "quickstart"
                ]
              },
              {
                "group": "自定义配置",
                "pages": [
                  "settings",
                  "users",
                  "features"
                ]
              },
              {
                "group": "计费管理",
                "pages": [
                  "billing/overview",
                  "billing/payments",
                  "billing/subscriptions"
                ]
              }
            ]
          },
          {
            "dropdown": "更新日志",
            "icon": "history",
            "description": "产品更新和变更记录",
            "pages": [
              "changelog"
            ]
          }
        ]
      },
      "logo": {
        "light": "/logo-light.svg",
        "dark": "/logo-dark.svg",
        "href": "https://example.com"
      },
      "navbar": {
        "links": [
          {
            "label": "社区",
            "href": "https://example.com/community"
          }
        ],
        "primary": {
          "type": "button",
          "label": "立即开始",
          "href": "https://example.com/start"
        }
      },
      "footer": {
        "socials": {
          "x": "https://x.com/example",
          "linkedin": "https://www.linkedin.com/company/example",
          "github": "https://github.com/example",
          "slack": "https://example.com/community"
        },
        "links": [
          {
            "header": "资源",
            "items": [
              {
                "label": "客户案例",
                "href": "https://example.com/customers"
              },
              {
                "label": "企业版",
                "href": "https://example.com/enterprise"
              },
              {
                "label": "申请试用",
                "href": "https://example.com/preview"
              }
            ]
          },
          {
            "header": "公司",
            "items": [
              {
                "label": "招聘信息",
                "href": "https://example.com/careers"
              },
              {
                "label": "博客",
                "href": "https://example.com/blog"
              },
              {
                "label": "隐私政策",
                "href": "https://example.com/legal/privacy"
              }
            ]
          }
        ]
      },
      "integrations": {
        "ga4": {
          "measurementId": "G-XXXXXXXXXX"
        },
        "koala": {
          "publicApiKey": "pk_example_key_123"
        },
        "telemetry": {
          "enabled": true
        },
        "cookies": {
          "key": "example_cookie_key",
          "value": "example_cookie_value"
        }
      },
      "contextual": {
        "options": [
          "copy",
          "view",
          "chatgpt",
          "claude"
        ]
      },
      "errors": {
        "404": {
          "redirect": false,
          "title": "页面未找到",
          "description": "这个_页面_到底**怎么了**？"
        }
      }
    }
    ```
  </Tab>

  <Tab title="交互式 API 示例">
    ```json title="docs.json" wrap lines highlight={43-61, 72-79} theme={null}
    {
      "$schema": "https://mintlify.com/docs.json",
      "theme": "maple",
      "name": "Example Co.",
      "description": "Example Co. 是一家提供示例内容和占位符文本的公司。",
      "colors": {
        "primary": "#3B82F6",
        "light": "#F8FAFC",
        "dark": "#0F172A"
      },
      "navigation": {
        "dropdowns": [
          {
            "dropdown": "文档",
            "icon": "book",
            "description": "如何使用 Example Co. 产品",
            "groups": [
              {
                "group": "快速入门",
                "pages": [
                  "index",
                  "quickstart"
                ]
              },
              {
                "group": "自定义配置",
                "pages": [
                  "settings",
                  "users",
                  "features"
                ]
              },
              {
                "group": "计费管理",
                "pages": [
                  "billing/overview",
                  "billing/payments",
                  "billing/subscriptions"
                ]
              }
            ]
          },
          {
            "dropdown": "API 参考",
            "icon": "terminal",
            "description": "如何使用 Example Co. API",
            "groups": [
              {
                "group": "API 参考",
                "pages": [
                  "api-reference/introduction"
                ]
              },
              {
                "group": "接口端点",
                "openapi": {
                  "source": "openapi.json"
                }
              }
            ]
          },
          {
            "dropdown": "更新日志",
            "icon": "history",
            "description": "更新和变更记录",
            "pages": [
              "changelog"
            ]
          }
        ]
      },
      "api": {
        "playground": {
          "display": "interactive"
        },
        "examples": {
          "languages": ["javascript", "curl", "python"]
        }
      },
      "logo": {
        "light": "/logo-light.svg",
        "dark": "/logo-dark.svg",
        "href": "https://example.com"
      },
      "navbar": {
        "links": [
          {
            "label": "社区",
            "href": "https://example.com/community"
          }
        ],
        "primary": {
          "type": "button",
          "label": "立即开始",
          "href": "https://example.com/start"
        }
      },
      "footer": {
        "socials": {
          "x": "https://x.com/example",
          "linkedin": "https://www.linkedin.com/company/example",
          "github": "https://github.com/example",
          "slack": "https://example.com/community"
        },
        "links": [
          {
            "header": "资源",
            "items": [
              {
                "label": "客户案例",
                "href": "https://example.com/customers"
              },
              {
                "label": "企业版",
                "href": "https://example.com/enterprise"
              },
              {
                "label": "申请预览",
                "href": "https://example.com/preview"
              }
            ]
          },
          {
            "header": "公司",
            "items": [
              {
                "label": "招聘信息",
                "href": "https://example.com/careers"
              },
              {
                "label": "博客",
                "href": "https://example.com/blog"
              },
              {
                "label": "隐私政策",
                "href": "https://example.com/legal/privacy"
              }
            ]
          }
        ]
      },
      "integrations": {
        "ga4": {
          "measurementId": "G-XXXXXXXXXX"
        },
        "koala": {
          "publicApiKey": "pk_example_key_123"
        },
        "telemetry": {
          "enabled": true
        },
        "cookies": {
          "key": "example_cookie_key",
          "value": "example_cookie_value"
        }
      },
      "contextual": {
        "options": [
          "copy",
          "view",
          "chatgpt",
          "claude"
        ]
      },
      "errors": {
        "404": {
          "redirect": false,
          "title": "页面未找到",
          "description": "这个**页面**到底_去哪了_？"
        }
      }
    }
    ```
  </Tab>

  <Tab title="多语言示例">
    ```json title="docs.json" wrap lines theme={null}
    {
      "$schema": "https://mintlify.com/docs.json",
      "theme": "maple",
      "name": "Example Co.",
      "description": "Example Co. 是一家提供示例内容和占位符文本的公司。",
      "colors": {
        "primary": "#3B82F6",
        "light": "#F8FAFC",
        "dark": "#0F172A"
      },
      "navigation": {
        "global": {
          "anchors": [
            {
              "anchor": "文档",
              "href": "https://mintlify.com/docs"
            },
            {
              "anchor": "更新日志",
              "href": "https://mintlify.com/docs/changelog"
            }
          ]
        },
        "languages": [ // [!code highlight:3]
          {
            "language": "en",
            "dropdowns": [
              {
                "dropdown": "文档",
                "icon": "book",
                "description": "如何使用 Example Co. 产品",
                "pages": [
                  {
                    "group": "快速入门",
                    "pages": ["index", "quickstart"]
                  },
                  {
                    "group": "自定义配置",
                    "pages": ["settings", "users", "features"]
                  },
                  {
                    "group": "计费管理",
                    "pages": [
                      "billing/overview",
                      "billing/payments",
                      "billing/subscriptions"
                    ]
                  }
                ]
              },
              {
                "dropdown": "更新日志",
                "icon": "history",
                "description": "更新和变更记录",
                "pages": ["changelog"]
              }
            ]
          },
          {
            "language": "es",// [!code highlight]
            "dropdowns": [
              {
                "dropdown": "文档",
                "icon": "book",
                "description": "如何使用 Example Co. 产品",
                "pages": [
                  {
                    "group": "快速入门",
                    "pages": ["es/index", "es/quickstart"]
                  },
                  {
                    "group": "自定义配置",
                    "pages": ["es/settings", "es/users", "es/features"]
                  },
                  {
                    "group": "计费管理",
                    "pages": [
                      "es/billing/overview",
                      "es/billing/payments",
                      "es/billing/subscriptions"
                    ]
                  }
                ]
              },
              {
                "dropdown": "更新日志",
                "icon": "history",
                "description": "更新和变更记录",
                "pages": ["es/changelog"]
              }
            ]
          }
        ]
      },
      "logo": {
        "light": "/logo-light.svg",
        "dark": "/logo-dark.svg",
        "href": "https://example.com"
      },
      "navbar": {
        "links": [
          {
            "label": "社区",
            "href": "https://example.com/community"
          }
        ],
        "primary": {
          "type": "button",
          "label": "立即开始",
          "href": "https://example.com/start"
        }
      },
      "footer": {
        "socials": {
          "x": "https://x.com/example",
          "linkedin": "https://www.linkedin.com/company/example",
          "github": "https://github.com/example",
          "slack": "https://example.com/community"
        },
        "links": [
          {
            "header": "资源",
            "items": [
              {
                "label": "客户案例",
                "href": "https://example.com/customers"
              },
              {
                "label": "企业版",
                "href": "https://example.com/enterprise"
              },
              {
                "label": "申请试用",
                "href": "https://example.com/preview"
              }
            ]
          },
          {
            "header": "公司",
            "items": [
              {
                "label": "招聘信息",
                "href": "https://example.com/careers"
              },
              {
                "label": "博客",
                "href": "https://example.com/blog"
              },
              {
                "label": "隐私政策",
                "href": "https://example.com/legal/privacy"
              }
            ]
          }
        ]
      },
      "integrations": {
        "ga4": {
          "measurementId": "G-XXXXXXXXXX"
        },
        "koala": {
          "publicApiKey": "pk_example_key_123"
        },
        "telemetry": {
          "enabled": true
        },
        "cookies": {
          "key": "example_cookie_key",
          "value": "example_cookie_value"
        }
      },
      "contextual": {
        "options": ["copy", "view", "chatgpt", "claude"]
      },
      "errors": {
        "404": {
          "redirect": false,
          "title": "页面未找到",
          "description": "这个**页面**到底_怎么了_？"
        }
      }
    }
    ```
  </Tab>
</Tabs>

<div id="upgrading-from-mintjson">
  ## 从 `mint.json` 升级
</div>

如果你的文档项目仍在使用已废弃的 `mint.json` 文件，请按以下步骤升级到 `docs.json`。

<Steps>
  <Step title="安装或更新命令行界面（CLI）">
    如果你尚未安装[命令行界面（CLI）](/zh/installation)，请先安装：

    <CodeGroup>
      ```bash npm theme={null}
      npm i -g mint
      ```

      ```bash yarn theme={null}
      yarn global add mint
      ```

      ```bash pnpm theme={null}
      pnpm add -g mint
      ```
    </CodeGroup>

    如果你已经安装了 CLI，请确保更新至最新版本：

    ```bash theme={null}
    mint update
    ```
  </Step>

  <Step title="创建 docs.json 文件">
    在你的文档存储库中运行：

    ```bash theme={null}
    mint upgrade
    ```

    该命令会基于现有的 `mint.json` 生成一个 `docs.json` 文件。请检查生成的文件，确保所有设置正确。
  </Step>

  <Step title="删除 mint.json 文件">
    在确认 `docs.json` 配置无误后，你即可安全删除旧的 `mint.json` 文件。
  </Step>
</Steps>