全局设置

docs.json 文件可将一组 Markdown 文件转换为可浏览、可自定义的文档站点。这个必填的配置文件控制样式、导航、integrations 等内容。可以把它看作你的文档蓝图。 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。查看主题以了解更多信息。

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。

显示 Logo

string

必填

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

string

必填

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

string (uri)

点击 logo 时跳转的 URL。若未提供，logo 将链接到你的首页。示例：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

缩略图的字体配置。仅支持 Google Fonts 的字体系列名称。

显示 Fonts

string

必填

字体系列名称，例如 “Open Sans” 或 “Playfair Display”。支持 Google Fonts 的字体系列名称。

object

视觉样式配置。

显示 Styling

"section" | "breadcrumbs"

页面 eyebrow 区域的样式。选择 section 显示所属章节名称，选择 breadcrumbs 显示完整导航路径。默认为 section。

boolean

控制是否包含 LaTeX 样式表，并覆盖自动检测。默认情况下，Mintlify 会自动检测内容中的 LaTeX 使用情况并加载所需的样式表。

设置为 true：当自动检测未能识别你的数学表达式时，强制加载 LaTeX 样式表。
设置为 false：如果你不使用数学表达式，但内容会触发误检，可阻止加载 LaTeX 样式表，以提升性能。

"system" | "dark" | string | object

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

"system"：匹配当前站点模式（light 或 dark）
"dark"：始终使用 dark 模式

自定义主题配置：

使用字符串为所有代码块指定单个 Shiki 主题
使用对象为 light 和 dark 模式分别指定不同的 Shiki 主题

string

一个同时用于 light 和 dark 两种模式的 Shiki 主题名称。

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

object

为 light 和 dark 模式分别指定不同的主题。

显示 theme

string

必填

light 模式下使用的 Shiki 主题名称。

string

必填

dark 模式下使用的 Shiki 主题名称。

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

object

代码块的自定义语言配置。

显示 languages

array of string

指向描述自定义 Shiki 语言的 JSON 文件的路径。使用此配置为 Shiki 默认不包含的语言添加语法高亮。JSON 文件必须遵循 Shiki 使用的 TextMate 语法格式。

"styling": {
  "codeblocks": {
    "languages": {
      "custom": ["/languages/my-custom-language.json"]
    }
  }
}

object

图标库设置。

显示 Icons

"fontawesome" | "lucide"

必填

在整个文档中使用的图标库。默认为 fontawesome。你在一个项目中只能使用一个图标库。文档中的所有图标名称都必须来自同一个图标库。

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

object

为文档设置自定义字体。默认字体随主题不同而变化。

显示 Fonts

string

必填

字体系列，例如 “Open Sans”。支持 Google Fonts 的 family 名称。

number

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

string (uri)

取以下之一：

托管字体的 URL，例如 https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2。
本地字体文件的路径，例如 /fonts/Hubot-Sans.woff2。

当你指定 Google 字体的 family 名称时，Google Fonts 会自动加载，因此无需提供 source URL。

"woff" | "woff2"

字体文件格式。使用 source 字段时必填。

object

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

显示 Heading

string

必填

字体系列，例如 “Open Sans”、“Playfair Display”。支持 Google Fonts 的 family 名称。

number

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

string (uri)

取以下之一：

托管字体的 URL，例如 https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2。
本地字体文件的路径，例如 /fonts/Hubot-Sans.woff2。

当你指定 Google 字体的 family 名称时，Google Fonts 会自动加载，因此无需提供 source URL。

"woff" | "woff2"

字体文件格式。使用 source 字段时必填。

object

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

显示 Body

string

必填

字体系列，例如 “Open Sans”、“Playfair Display”。支持 Google Fonts 的 family 名称。

number

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

string (uri)

取以下之一：

托管字体的 URL，例如 https://mintlify-assets.b-cdn.net/fonts/Hubot-Sans.woff2。
本地字体文件的路径，例如 /fonts/Hubot-Sans.woff2。

当你指定 Google 字体的 family 名称时，Google Fonts 会自动加载，因此无需提供 source URL。

"woff" | "woff2"

字体文件格式。使用 source 字段时必填。

object

明/暗模式切换设置。

显示 Appearance

"system" | "light" | "dark"

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

boolean

是否隐藏明/暗模式切换。默认为 false。

object

背景颜色与装饰设置。

显示 Background

string or object

站点的背景图像。可以是单个文件，或分别为 light 与 dark 模式提供独立文件。

显示 Image

string

必填

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

string

必填

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

"gradient" | "grid" | "windows"

主题的背景装饰效果。

object

为 light 与 dark 模式自定义背景颜色。

显示 Color

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

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

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

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

结构

导航栏中的外部链接项目。

显示 Navbar

array of object

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

显示 Links

string

必填

链接文本。

string (uri)

必填

链接目标。必须为有效的外部 URL。

string

要显示的 icon。选项：

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

针对自定义 SVG icon：

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

string

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

object

导航栏中的主按钮。

显示 Primary

"button" | "github"

必填

按钮样式。选择 button 以使用带有文本的标准按钮，选择 github 以使用指向 GitHub 存储库并带 icon 的链接。

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

要显示的 icon。选项：

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

针对自定义 SVG icon：

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

string

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

boolean

是否默认隐藏此标签页。

string (uri)

必填

该标签页目标的 URL 或路径。

array of object

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

显示 Anchors

string

必填

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

string

要显示的 icon。选项：

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

针对自定义 SVG icon：

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

string

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

object

锚点的自定义颜色。

显示 Color

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

适用于 light 模式的锚点颜色。必须是以 # 开头的十六进制代码。

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

适用于 system 模式的锚点颜色。必须是以 # 开头的十六进制代码。

boolean

是否默认隐藏此锚点。

string (uri)

必填

锚点目标的 URL 或路径。

array of object

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

显示下拉菜单

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

string

要显示的 icon。选项：

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

针对自定义 SVG icon：

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

string

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

boolean

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

string (uri)

必填

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

array of object

用于将内容分组为不同部分的产品。

显示 Products

string

必填

产品的显示名称。

string

产品的描述。

string

要显示的 icon。选项：

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

针对自定义 SVG icon：

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

string

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

array of object

用于multi-language站点的语言切换器。

array of object

为拥有多个版本的网站提供版本切换器。

array of object

顶级导航的 Tabs。

array of object

侧边栏中的锚点。

array of object

用于对相关内容进行分组的下拉菜单。

array of object

适用于包含多个产品的站点的产品切换器。

array of object

用于将内容组织成各个部分的groups。

array of string or object

构成你的文档的独立页面。

object

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

显示 Interaction

boolean

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

object

文档页面的元数据配置。

显示 Metadata

boolean

在所有页面上启用最后修改日期显示。启用后，所有页面都会显示内容的最后修改日期。默认为 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

必填

横幅中显示的文本内容。支持基础 MDX 格式，包括链接、加粗和斜体文本。不支持自定义组件。例如：

{
  "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 服务器。

将自定义上下文菜单选项定义为包含以下属性的对象：

显示 Custom option

string

必填

自定义选项的显示标题。

string

必填

自定义选项的说明文本。

string

自定义选项的图标。支持图标库名称、URL、路径或 SVG 代码。

string or object

必填

自定义选项的链接目标。可以是简单的 URL 字符串，或带有 base 和可选 query 参数的对象。占位符值：

$page: 当前页面内容
$path: 当前页面路径
$mcp: MCP 服务器 URL

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

API 配置

object

API 文档和交互式操作台的设置。

显示 API

string or array or object

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

显示 openapi

string

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

string

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

"openapi": "openapi.json"

"openapi": [
  "openapi/v1.json",
  "openapi/v2.json",
  "https://api.example.com/openapi.yaml"
]

"openapi": {
  "source": "openapi.json",
  "directory": "api-docs"
}

string or array or object

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

显示 asyncapi

string

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

string

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

"asyncapi": "asyncapi.json"

"asyncapi": [
  "asyncapi/events.yaml",
  "asyncapi/webhooks.yaml",
  "https://api.example.com/asyncapi.json"
]

"asyncapi": {
  "source": "asyncapi.json",
  "directory": "websockets"
}

object

API 参数的显示设置。

显示 Params

"all" | "closed"

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

object

API 操作台设置。

显示 Playground

"interactive" | "simple" | "none"

API 操作台的显示模式。默认为 interactive。

boolean

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

object

自动生成的 API 示例的配置。

显示 Examples

array of string

自动生成的 API 代码片段所使用的示例语言。支持的语言包括：

bash（显示为 cURL）
go
java
javascript
node（显示为 Node.js）
php
powershell
python
ruby
swift

也支持常见别名：curl、golang、js、nodejs、rb、sh。

"required" | "all"

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

boolean

是否使用 schema 示例数据预填 API 操作台。启用后，操作台会自动使用 OpenAPI 规范中的示例值填充请求字段。默认为 false。

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 标签。必须为有效的 key-value 对。可参考常用 Meta 标签获取可选项。

"navigable" | "all"

指定哪些页面应被搜索引擎索引。选择 navigable 仅索引位于 docs.json 中 navigation 的页面，选择 all 则索引所有页面。默认值为 navigable。

object

搜索显示设置。

显示 Search

string

搜索栏中的占位文本。

集成

object

第三方集成。

显示集成

object

Amplitude 分析集成。

显示 Amplitude

string

必填

您的 Amplitude API 密钥。

object

Microsoft Clarity 集成。

显示 Clarity

string

必填

您的 Microsoft Clarity 项目 ID。

object

Clearbit 数据富集集成。

显示 Clearbit

string

必填

你的 Clearbit API 密钥。

object

Fathom Analytics 集成。

显示 Fathom

string

必填

你在 Fathom 中的站点 ID。

object

Front Chat 集成。

显示 Frontchat

string

必填

您的 Front Chat 代码片段 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 Analytics 集成。

显示 Heap

string

必填

您的 Heap 应用 ID。

object

Hightouch 集成。

显示 Hightouch

string

必填

你的 Hightouch write key。

string

你的 Hightouch API 主机地址。

object

Hotjar 集成。

显示 Hotjar

string

必填

您的 Hotjar ID。

string

必填

您的 Hotjar 脚本版本。

object

Intercom 集成。

显示 Intercom

string

必填

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

object

LogRocket 集成。

显示 Logrocket

string

必填

您的 LogRocket 应用 ID。

object

Mixpanel 集成。

显示 Mixpanel

string

必填

你的 Mixpanel 项目 token。

object

Osano 集成。

显示 Osano

string

必填

你的 Osano 脚本源。

object

Pirsch Analytics 集成。

显示 Pirsch

string

必填

您的 Pirsch ID。

object

PostHog 集成。

显示 Posthog

string matching ^phc\_

必填

你的 PostHog API key。必须匹配模式：^phc_

string (uri)

你的 PostHog API 主机地址。

object

Plausible Analytics 集成。

显示 Plausible

string

必填

您的 Plausible 域名。

string

您的 Plausible 服务器。

object

Segment 集成。

显示 Segment

string

必填

您的 Segment key。

object

遥测/使用数据设置。

显示遥测/使用数据

boolean

是否启用遥测/使用数据。

当该值为 false 时，反馈功能也会被禁用，并且不会显示在你的文档页面上。

Cookie 设置。

显示 Cookies

string

Cookie 的 key。

string

Cookie 的值。

错误

object

错误处理设置。

显示错误

object

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

显示 404

boolean

页面未找到时是否自动重定向到首页。默认值为 true。

string

404 错误页面的自定义 title。

string

404 错误页面的自定义说明。支持基本 MDX 格式，包括链接、加粗和斜体文本。不支持自定义组件。

示例

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

docs.json

{
  "$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"
    },
    "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": {
    "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"
    },
    "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"
    },
    "telemetry": {
      "enabled": true
    },
    "cookies": {
      "key": "example_cookie_key",
      "value": "example_cookie_value"
    }
  },
  "contextual": {
    "options": ["copy", "view", "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 文件。

快速开始

整理

自定义

创建内容

API 文档

部署

优化

配置你的 `docs.json`

参考

自定义

结构

API 配置

SEO 和搜索

集成

错误

示例

从 `mint.json` 升级

​配置你的 docs.json

​参考

​自定义

​结构

​API 配置

​SEO 和搜索

​集成

​错误

​示例

​从 mint.json 升级

配置你的 `docs.json`

参考

自定义

结构

API 配置

SEO 和搜索

集成

错误

示例

从 `mint.json` 升级