全局设置

docs.json 文件可将一组 Markdown 文件构建为可导航、可定制的文档站点。这个必需的配置文件控制样式、导航、集成等内容。可以把它看作你的文档蓝图。 docs.json 中的设置会全局应用于所有页面。

配置你的 `docs.json`

入门时，你只需指定 theme、name、colors.primary 和 navigation。其他字段都是可选的，可随着文档需求增长再逐步添加。为获得最佳编辑体验，请在 docs.json 文件顶部加入模式（schema）引用。这将在大多数代码编辑器中启用自动补全、验证和实用的悬浮提示：

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

参考

本节提供 docs.json 文件的完整参考说明。

自定义

必填

站点的布局主题。可选值：mint、maple、palm、willow、linden、almond、aspen。更多信息请参见 Themes。

string

必填

项目、组织或产品的名称。

object

必填

文档中使用的配色。不同主题的用色方式不同。若仅提供主色，则会用于所有颜色元素。

显示 Colors

string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

必填

文档的主色。通常用于浅色模式中的强调，具体随主题有所差异。必须是以 # 开头的十六进制色值。

string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

深色模式下用于强调的颜色。必须是以 # 开头的十六进制色值。

string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

在浅色与深色模式中用于按钮和悬停状态的颜色，具体随主题有所差异。必须是以 # 开头的十六进制色值。

string

站点描述，用于 SEO 和 AI 索引。

string or object

适用于浅色和深色模式的徽标。

显示 Logo

string

必填

指向浅色模式徽标文件的路径。需包含文件扩展名。示例：/logo.png

string

必填

指向深色模式徽标文件的路径。需包含文件扩展名。示例：/logo-dark.png

string (uri)

点击徽标时跳转的 URL。若未提供，徽标将链接至你的主页。示例：https://mintlify.com

string or object

指向 favicon 文件的路径，需包含文件扩展名。将自动调整为合适的 favicon 尺寸。可为单个文件，或分别提供浅色与深色模式的文件。示例：/favicon.png

显示 Favicon

string

必填

指向浅色模式 favicon 文件的路径。需包含文件扩展名。示例：/favicon.png

string

必填

指向深色模式 favicon 文件的路径。需包含文件扩展名。示例：/favicon-dark.png

object

用于社交媒体与页面预览的缩略图自定义。

显示 Thumbnails

"light" | "dark"

缩略图的视觉主题。若未指定，缩略图将使用由 colors 字段定义的站点配色方案。

string

缩略图的背景图像。可为相对路径或绝对 URL。

object

视觉样式配置。

显示 Styling

"section" | "breadcrumbs"

页面眉导航（eyebrow）的样式。选择 section 显示所属分区名称，或选择 breadcrumbs 显示完整导航路径。默认为 section。

"system" | "dark" | object

代码块主题配置。默认为 "system"。简单选项：

"system"：跟随站点当前模式（浅色或深色）
"dark"：始终使用深色模式

自定义主题配置： 使用对象指定 Shiki 主题。可以为两种模式共用一个主题，或分别为浅色与深色设置不同主题。

显示 codeblocks

string

同时用于浅色与深色模式的单个 Shiki 主题名称。

"styling": {
  "codeblocks": {
    "theme": "dracula"
  }
}

object

为浅色与深色模式分别设置主题。

显示 themes

string

必填

浅色模式的 Shiki 主题名称。

string

必填

深色模式的 Shiki 主题名称。

"styling": {
  "codeblocks": {
    "themes": {
      "light": "github-light",
      "dark": "github-dark"
    }
  }
}

object

图标库设置。

显示 Icons

"fontawesome" | "lucide"

必填

在整个文档中使用的图标库。默认为 fontawesome。

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

object

文档的字体配置。默认字体为 Inter。

显示 Fonts

string

必填

字体系列，例如 “Open Sans”、“Playfair Display”。

number

字重，例如 400 或 700。可变字体支持精确字重，例如 550。

string (uri)

字体源的 URL，例如 https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2。当你指定 Google Fonts 的 family 名称时，Google Fonts 会自动加载，因此无需提供源 URL。

"woff" | "woff2"

字体文件格式。

object

覆盖标题的专用字体设置。

显示 Heading

string

必填

字体系列，例如 “Open Sans”、“Playfair Display”。

number

字重，例如 400、700。可变字体支持精确字重，例如 550。

string (uri)

字体源的 URL，例如 https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2。当你指定 Google Fonts 的 family 名称时，Google Fonts 会自动加载，因此无需提供源 URL。

"woff" | "woff2"

字体文件格式。

object

覆盖正文的专用字体设置。

显示 Body

string

必填

字体系列，例如 “Open Sans”、“Playfair Display”。

number

字重，例如 400、700。可变字体支持精确字重，例如 550。

string (uri)

字体源的 URL，例如 https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2。当你指定 Google Fonts 的 family 名称时，Google Fonts 会自动加载，因此无需提供源 URL。

"woff" | "woff2"

字体文件格式。

object

明暗模式切换设置。

显示 Appearance

"system" | "light" | "dark"

默认主题模式。选择 system 以匹配用户的操作系统设置，或选择 light 或 dark 以强制使用特定模式。默认值为 system。

boolean

是否隐藏明暗模式切换。默认值为 true。

object

背景颜色与装饰设置。

显示 Background

string or object

站点的背景图像。可以是单个文件，也可以分别为浅色和深色模式提供不同文件。

显示 Image

string

必填

浅色模式下背景图像的路径。需包含文件扩展名。示例：/background.png。

string

必填

深色模式下背景图像的路径。需包含文件扩展名。示例：/background-dark.png。

"gradient" | "grid" | "windows"

主题的背景装饰样式。

object

自定义浅色与深色模式下的背景颜色。

显示 Color

string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

浅色模式的背景颜色。必须为以 # 开头的十六进制色值。

string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

深色模式的背景颜色。必须为以 # 开头的十六进制色值。

结构

导航栏条目。

显示 Navbar

array of object

要在导航栏中显示的链接。

显示 Links

string

必填

链接文本。

string (uri)

必填

链接目标的 URL 或路径。

string

要显示的图标。选项：

Font Awesome 图标名称
Lucide 图标名称
用花括号包裹的、与 JSX 兼容的 SVG 代码
指向外部托管图标的 URL
项目中图标文件的路径

关于自定义 SVG 图标：

使用 SVGR 转换器转换你的 SVG。
将 SVG 代码粘贴到 SVG 输入框。
从 JSX 输出框中复制完整的 <svg>...</svg> 元素。
用花括号包裹与 JSX 兼容的 SVG 代码：icon={<svg ...> ... </svg>}。
按需调整 height 和 width。

string

Font Awesome 图标样式。仅在使用 Font Awesome 图标时生效。选项：regular、solid、light、thin、sharp-solid、duotone、brands。

object

导航栏中的主按钮。

显示 Primary

"button" | "github"

必填

按钮样式。选择 button 为带文本的标准按钮，或选择 github 为带图标的 GitHub 仓库链接。

string

必填

按钮文本。仅当 type 为 button 时生效。

string (uri)

必填

按钮链接目标。必须是有效路径或外部 URL。若 type 为 github，必须是 GitHub 仓库的 URL。

object

必填

你的内容导航结构。

显示导航

object

在所有页面和部分中显示的全局导航元素。

显示全局

array of object

面向本地化站点的语言切换器配置。

显示 Languages

"en" | "cn" | "zh" | "zh-Hans" | "zh-Hant" | "es" | "fr" | "ja" | "jp" | "pt" | "pt-BR" | "de" | "ko" | "it" | "ru" | "id" | "ar" | "tr"

必填

ISO 639-1 格式的语言代码。

boolean

是否为默认语言。

boolean

是否默认隐藏此语言选项。

string (uri)

必填

指向该语言文档版本的有效路径或外部链接。

array of object

用于多版本站点的版本切换器配置。

显示 Versions

string

必填

版本的显示名称。最小长度：1

boolean

是否为默认版本。

boolean

是否默认隐藏此版本选项。

string (uri)

必填

指向该文档版本的 URL 或路径。

array of object

用于组织主要版块的顶级导航标签页。

显示 Tabs

string

必填

标签页的显示名称。最小长度：1

string

要显示的图标。选项：

Font Awesome 图标名称
Lucide 图标名称
用花括号包裹的、与 JSX 兼容的 SVG 代码
指向外部托管图标的 URL
项目中图标文件的路径

关于自定义 SVG 图标：

使用 SVGR 转换器转换你的 SVG。
将 SVG 代码粘贴到 SVG 输入框。
从 JSX 输出框中复制完整的 <svg>...</svg> 元素。
用花括号包裹与 JSX 兼容的 SVG 代码：icon={<svg ...> ... </svg>}。
按需调整 height 和 width。

string

Font Awesome 图标样式。仅在使用 Font Awesome 图标时生效。选项：regular、solid、light、thin、sharp-solid、duotone、brands。

boolean

是否默认隐藏此标签页。

string (uri)

必填

标签页目标的 URL 或路径。

array of object

在侧边栏导航中突出显示的锚点链接。

显示 Anchors

string

必填

锚点的显示名称。最小长度：1

string

要显示的图标。选项：

Font Awesome 图标名称
Lucide 图标名称
用花括号包裹的、与 JSX 兼容的 SVG 代码
指向外部托管图标的 URL
项目中图标文件的路径

关于自定义 SVG 图标：

使用 SVGR 转换器转换你的 SVG。
将 SVG 代码粘贴到 SVG 输入框。
从 JSX 输出框中复制完整的 <svg>...</svg> 元素。
用花括号包裹与 JSX 兼容的 SVG 代码：icon={<svg ...> ... </svg>}。
按需调整 height 和 width。

string

Font Awesome 图标样式。仅在使用 Font Awesome 图标时生效。选项：regular、solid、light、thin、sharp-solid、duotone、brands。

object

锚点的自定义颜色。

显示 Color

string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

亮色模式下的锚点颜色。必须是以 # 开头的十六进制色值。

string matching ^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$

暗色模式下的锚点颜色。必须是以 # 开头的十六进制色值。

boolean

是否默认隐藏此锚点。

string (uri)

必填

指向锚点目标的 URL 或路径。

array of object

用于组织相关内容的下拉菜单。

显示 Dropdowns

下拉菜单的显示名称。最小长度：1

string

要显示的图标。选项：

Font Awesome 图标名称
Lucide 图标名称
用花括号包裹的、与 JSX 兼容的 SVG 代码
指向外部托管图标的 URL
项目中图标文件的路径

关于自定义 SVG 图标：

使用 SVGR 转换器转换你的 SVG。
将 SVG 代码粘贴到 SVG 输入框。
从 JSX 输出框中复制完整的 <svg>...</svg> 元素。
用花括号包裹与 JSX 兼容的 SVG 代码：icon={<svg ...> ... </svg>}。
按需调整 height 和 width。

string

Font Awesome 图标样式。仅在使用 Font Awesome 图标时生效。选项：regular、solid、light、thin、sharp-solid、duotone、brands。

boolean

是否默认隐藏该下拉菜单。

string (uri)

必填

下拉菜单目标的URL或路径。

array of object

用于多语言站点的语言切换器。

array of object

用于含有多个版本的网站的版本切换器。

array of object

顶级导航选项卡。

array of object

侧边栏中的锚点。

array of object

用于将相关内容分组的下拉菜单。

array of object

用于将内容组织成章节的 Groups。

array of string or object

构成你文档的单个页面。

object

导航元素的用户交互设置。

显示 Interaction

boolean

控制选择导航分组时的自动导航行为。设置为 true 时，展开导航分组将自动跳转到该分组的第一个页面；设置为 false 时，将不会跳转，仅展开或折叠分组；不设置则采用主题的默认行为。

object

页脚内容与社交媒体链接。

显示 Footer

object

在页脚中展示的社交媒体账号。每个键为平台名称，每个值为你的账号 URL。例如：

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

array of object

在页脚中展示的链接。

显示 Links

string

列标题。最小长度：1

array of object

必填

此列中要展示的链接。

显示 Items

string

必填

链接文本。最小长度：1

string (uri)

必填

链接目标 URL。

object

显示在页面顶部的全站横幅。

显示 Banner

string

横幅内容。支持纯文本与 Markdown 格式。例如：

{
  "content": "🚀 Banner is live! [Learn more](mintlify.com)"
}

boolean

用户是否可以关闭横幅。默认值为 false。

array of object

为已移动、重命名或删除的页面配置重定向。

显示 Redirects

string

必填

重定向来源路径。示例：/old-page

string

必填

重定向目标路径。示例：/new-page

boolean

是否使用永久重定向（301）。默认值为 true。

object

用于 AI 优化内容与集成的上下文菜单。

显示 Contextual

必填

上下文菜单中可用的操作。第一个选项将作为默认项显示。

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

上下文菜单仅在预览与生产环境的部署中可用。

API 配置

object

API 文档与 API交互测试台的设置。

显示 Api

string or array or object

用于生成 API 文档的 OpenAPI规范文件。可以是单个 URL/路径，或由多个 URL/路径构成的数组。

显示 Openapi

string

你的 OpenAPI规范文件的 URL 或路径。最小长度：1

string

用于搜索 OpenAPI 文件的目录。不要包含前导斜杠。

string or array or object

用于生成 API 文档的 AsyncAPI规范文件。可以是单个 URL/路径，或由多个 URL/路径构成的数组。

显示 Asyncapi

string

你的 AsyncAPI规范文件的 URL 或路径。最小长度：1

string

用于搜索 AsyncAPI 文件的目录。不要包含前导斜杠。

object

API 参数的显示设置。

显示 Params

"all" | "closed"

是否默认展开所有参数。默认为 closed。

object

API交互测试台的设置。

显示 Playground

"interactive" | "simple" | "none"

API交互测试台的显示模式。默认为 interactive。

boolean

是否通过代理服务器转发 API 请求。默认为 true。

object

自动生成的 API 示例配置。

显示 Examples

array of string

自动生成的 API 代码片段的示例语言

"required" | "all"

是否在 API 示例中显示可选参数。默认为 all。

object

由 MDX 文件生成的 API 页面配置。

显示 Mdx

object

基于 MDX 的 API 请求的认证配置。

显示 Auth

"bearer" | "basic" | "key" | "cobo"

API 请求的认证方式。

string

API 请求的认证名称。

string or array

API 请求的服务器配置。

SEO 与搜索

object

SEO 索引配置。

显示 Seo

object

将添加到每个页面的 Meta 标签。必须为有效的键值对。参见常用 Meta 标签参考以查看可选项。

"navigable" | "all"

指定搜索引擎应索引的页面范围。选择 navigable 仅索引出现在 docs.json 导航中的页面，选择 all 则索引所有页面。默认值为 navigable。

object

搜索显示设置。

显示 Search

string

搜索栏中的占位文本。

集成

object

第三方集成。

显示集成

object

Amplitude 分析集成。

显示 Amplitude

string

必填

您的 Amplitude API 密钥。

object

Clearbit 数据富化集成。

显示 Clearbit

string

必填

你的 Clearbit API 密钥。

object

Fathom 分析集成。

显示 Fathom

string

必填

你的 Fathom 站点 ID。

object

Front 聊天集成。

显示 Frontchat

string

必填

你的 Front 聊天代码片段 ID。最小长度：6

object

Google Analytics 4 集成。

显示 GA4

string matching ^G

必填

你的 Google Analytics 4 测量 ID。必须匹配模式：^G

object

Google Tag Manager 集成。

显示 Gtm

string matching ^G

必填

你的 Google Tag Manager 标签 ID。必须符合模式：^G

object

Heap 分析集成。

显示 Heap

string

必填

您的 Heap 应用 ID。

object

Hotjar 集成。

显示 Hotjar

string

必填

您的 Hotjar ID。

string

必填

您的 Hotjar 脚本版本。

object

Intercom 集成。

显示 Intercom

string

必填

您的 Intercom 应用 ID。最小长度：6

object

Koala 集成。

显示 Koala

string

必填

您的 Koala 公共 API 密钥。最小长度：2

object

LogRocket 集成。

显示 LogRocket

string

必填

您的 LogRocket 应用 ID。

object

Mixpanel 集成。

显示 Mixpanel

string

必填

您的 Mixpanel 项目令牌。

object

Osano 集成。

显示 Osano

string

必填

你的 Osano 脚本源。

object

Pirsch 分析集成。

显示 Pirsch

string

必填

您的 Pirsch ID。

object

PostHog 集成。

显示 PostHog

string matching ^phc\_

必填

您的 PostHog API 密钥。必须符合模式：^phc_

string (uri)

您的 PostHog API 主机地址。

object

Plausible 分析集成。

显示 Plausible

string

必填

您的 Plausible 域名。

string

您的 Plausible 服务器。

object

Segment 集成。

显示 Segment

string

必填

您的 Segment Key。

object

遥测设置。

显示遥测

boolean

是否启用遥测。

Cookie 设置。

显示 Cookies

string

Cookie 的键。

string

Cookie 的值。

错误

object

错误处理设置。

显示 Errors

object

404“页面未找到”错误的处理方式。

显示 404

boolean

页面未找到时是否自动重定向到首页。

string

404 错误页的自定义标题。

string

404 错误页的自定义描述。支持 Markdown 格式。

示例

基础示例
交互式API示例
多语言示例

文档配置文件

{
  "$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": "这个页面发生了什么？"
    }
  }
}

文档配置文件

{
  "$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": "交互式",
    },
    "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": "这个页面发生了什么？"
    }
  }
}

docs.json

{
  "$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": [ 
      {
        "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",
        "dropdowns": [
          {
            "dropdown": "Documentación",
            "icon": "book",
            "description": "Cómo usar el producto de Example Co.",
            "pages": [
              {
                "group": "Comenzando",
                "pages": ["es/index", "es/quickstart"]
              },
              {
                "group": "Personalización",
                "pages": ["es/settings", "es/users", "es/features"]
              },
              {
                "group": "Billing",
                "pages": [
                  "es/billing/overview",
                  "es/billing/payments",
                  "es/billing/subscriptions"
                ]
              }
            ]
          },
          {
            "dropdown": "Changelog",
            "icon": "history",
            "description": "Actualizaciones y cambios",
            "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": ["复制", "查看", "chatgpt", "claude"],
  },
  "errors": {
    "404": {
      "redirect": false,
      "title": "找不到页面",
      "description": "这页发生了什么事？"
    }
  }
}

从 `mint.json` 升级

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

安装或更新 CLI

如果你尚未安装 CLI，请先安装：

npm i -g mint

yarn global add mint

pnpm add -g mint

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

mint update

创建 docs.json 文件

在你的文档仓库中运行：

mint upgrade

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

删除 mint.json 文件

在确认 docs.json 配置无误后，你可以安全删除旧的 mint.json 文件。

快速入门

核心配置

AI 优化

组件

API 页面

认证与个性化

指南

集成

版本控制与CI/CD

配置你的 `docs.json`

参考

自定义

结构

API 配置

SEO 与搜索

集成

错误

示例

从 `mint.json` 升级

​配置你的 docs.json

​参考

​自定义

​结构

​API 配置

​SEO 与搜索

​集成

​错误

​示例

​从 mint.json 升级

配置你的 `docs.json`

参考

自定义

结构

API 配置

SEO 与搜索

集成

错误

示例

从 `mint.json` 升级