> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-docs-automation-github-pr-review.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# docs.json schema 参考
> 所有 `docs.json` 配置属性的完整参考，包含类型、默认值和描述。
必需字段有 必需 标记。所有其他字段都是可选的。
有关每组设置的功能说明，请参阅主题页面：
* [外观与品牌](/zh/organize/settings-appearance)
* [站点结构](/zh/organize/settings-structure)
* [API 设置](/zh/organize/settings-api)
* [集成](/zh/organize/settings-integrations)
* [SEO 和搜索](/zh/organize/settings-seo)
## 快速参考
| 属性 | 类型 | 必需 | 默认值 |
| ---------------------------- | ----------------------------------------------------- | -- | --------------- |
| `$ref` | string（文件路径） | 否 | 无 |
| `theme` | string | 是 | 无 |
| `name` | string | 是 | 无 |
| `colors.primary` | string (hex) | 是 | 无 |
| `navigation` | object | 是 | 无 |
| `description` | string | 否 | 无 |
| `logo` | string 或 object | 否 | 无 |
| `favicon` | string 或 object | 否 | 无 |
| `appearance.default` | `"system"` \| `"light"` \| `"dark"` | 否 | `"system"` |
| `appearance.strict` | boolean | 否 | `false` |
| `fonts.family` | string | 否 | 主题默认 |
| `icons.library` | `"fontawesome"` \| `"lucide"` \| `"tabler"` | 否 | `"fontawesome"` |
| `background.decoration` | `"gradient"` \| `"grid"` \| `"windows"` | 否 | 无 |
| `styling.eyebrows` | `"section"` \| `"breadcrumbs"` | 否 | `"section"` |
| `styling.latex` | boolean | 否 | 自动检测 |
| `styling.codeblocks` | `"system"` \| `"dark"` \| string \| object | 否 | `"system"` |
| `thumbnails.appearance` | `"light"` \| `"dark"` | 否 | 站点默认 |
| `navbar.links` | array | 否 | 无 |
| `navbar.primary` | object | 否 | 无 |
| `footer.socials` | object | 否 | 无 |
| `footer.links` | array | 否 | 无 |
| `banner.content` | string | 否 | 无 |
| `banner.dismissible` | boolean | 否 | `false` |
| `banner.type` | `"info"` \| `"warning"` \| `"critical"` | 否 | `"info"` |
| `banner.color` | object \| string | 否 | 无 |
| `interaction.drilldown` | boolean | 否 | 主题默认 |
| `contextual.options` | array | 否 | 无 |
| `contextual.display` | `"header"` \| `"toc"` | 否 | `"header"` |
| `redirects` | array | 否 | 无 |
| `variables` | object | 否 | 无 |
| `metadata.timestamp` | boolean | 否 | `false` |
| `errors.404.redirect` | boolean | 否 | `true` |
| `errors.404.title` | string | 否 | 无 |
| `errors.404.description` | string | 否 | 无 |
| `api.openapi` | string 或 array 或 object | 否 | 无 |
| `api.asyncapi` | string 或 array 或 object | 否 | 无 |
| `api.playground.display` | `"interactive"` \| `"simple"` \| `"none"` \| `"auth"` | 否 | `"interactive"` |
| `api.playground.proxy` | boolean | 否 | `true` |
| `api.playground.credentials` | boolean | 否 | `false` |
| `api.params.expanded` | `"all"` \| `"closed"` | 否 | `"closed"` |
| `api.params.post` | array of string | 否 | 无 |
| `api.url` | `"full"` | 否 | 无 |
| `api.examples.languages` | string 数组 | 否 | 无 |
| `api.examples.defaults` | `"required"` \| `"all"` | 否 | `"all"` |
| `api.examples.prefill` | boolean | 否 | `false` |
| `api.examples.autogenerate` | boolean | 否 | `true` |
| `seo.indexing` | `"navigable"` \| `"all"` | 否 | `"navigable"` |
| `seo.metatags` | object | 否 | 无 |
| `search.prompt` | string | 否 | 无 |
| `integrations.*` | object | 否 | 无 |
## 完整属性参考
### `$ref`
从另一个 JSON 文件加载配置。在 `docs.json` 的任何级别使用 `$ref` 将配置拆分到多个文件中。
**类型：** string—指向 `.json` 文件的相对文件路径
* 当 `$ref` 解析为对象时，Mintlify 会将同一块中的兄弟键合并到引用内容之上，使这些键优先于引用中的匹配键。
* 当 `$ref` 解析为非对象值（如数组）时，Mintlify 会忽略任何兄弟键。
* 被引用的文件可以包含自己的 `$ref` 条目，路径相对于该文件解析。
* 路径必须保持在项目根目录内。循环引用会导致构建错误。
参见[使用 `$ref` 拆分配置](/zh/organize/settings#split-configuration-with-%24ref)了解示例。
***
### `theme` - 必需
站点的布局主题。
**类型：** string
**选项：** `mint`、`maple`、`palm`、`willow`、`linden`、`almond`、`aspen`、`sequoia`、`luma`
请参阅[主题](/zh/customize/themes)获取预览。
***
### `name` - 必需
你的项目、组织或产品的名称。
**类型：** string
***
### `colors` - 必需
文档中使用的颜色。
**类型：** object
#### `colors.primary`
必需
主色。通常在浅色模式下用于强调。
**类型：** string—匹配 `^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$` 的十六进制代码
#### `colors.light`
在深色模式下用于强调的颜色。
**类型：** string—匹配 `^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$` 的十六进制代码
#### `colors.dark`
在两种模式下用于按钮和悬停状态的颜色。
**类型：** string—匹配 `^#([a-fA-F0-9]{6}|[a-fA-F0-9]{3})$` 的十六进制代码
***
### `navigation` - 必需
内容的导航结构。
**类型：** object
请参阅[导航](/zh/organize/navigation)获取完整文档。
#### `navigation.global.languages`
全局导航栏中的语言切换器。
**类型：** object 数组—每项包含：`language`（string，必需）、`default`（boolean）、`hidden`（boolean）、`href`（string uri，必需）
**支持的语言代码：** `ar`、`ca`、`cn`、`cs`、`de`、`en`、`es`、`fr`、`fr-CA`、`he`、`hi`、`hu`、`id`、`it`、`ja`、`jp`、`ko`、`lv`、`nl`、`no`、`pl`、`pt`、`pt-BR`、`ro`、`ru`、`sv`、`tr`、`uk`、`uz`、`vi`、`zh`、`zh-Hans`、`zh-Hant`
#### `navigation.languages`
多语言站点的语言切换器。每个条目可以包含特定语言的 `banner`、`footer` 和 `navbar` 覆盖配置。
**类型：** object 数组—每项包含：`language`（string，必需）、`default`（boolean）、`hidden`（boolean）、`banner`（object）、`footer`（object）、`navbar`（object）
**支持的语言代码：** `ar`、`ca`、`cn`、`cs`、`de`、`en`、`es`、`fr`、`fr-CA`、`he`、`hi`、`hu`、`id`、`it`、`ja`、`jp`、`ko`、`lv`、`nl`、`no`、`pl`、`pt`、`pt-BR`、`ro`、`ru`、`sv`、`tr`、`uk`、`uz`、`vi`、`zh`、`zh-Hans`、`zh-Hant`
#### `navigation.directory`
导航分组中根页面的目录布局。递归继承；后代可以覆盖。参见[目录列表](/zh/organize/navigation#directory-listings)。
**类型：** `"none"` | `"accordion"` | `"card"`—默认值 `"none"`
***
### `description`
站点描述，用于 SEO 和 AI 索引。
**类型：** string
***
### `logo`
站点 logo。提供路径字符串或单独的 `light` 和 `dark` 对象。
**类型：** string 或 object
#### `logo.light`
必需（使用 object 形式时）
浅色模式下 logo 的路径。示例：`/logo/light.svg`。
**类型：** string
#### `logo.dark`
必需（使用 object 形式时）
深色模式下 logo 的路径。示例：`/logo/dark.svg`。
**类型：** string
#### `logo.href`
点击 logo 时重定向到的 URL。
**类型：** string (uri)
***
### `favicon`
站点 favicon。会自动调整大小。提供路径字符串或单独的 `light` 和 `dark` 对象。
**类型：** string 或 object
***
### `appearance`
浅色/深色模式设置。
**类型：** object
#### `appearance.default`
默认颜色模式。
**类型：** `"system"` | `"light"` | `"dark"`
**默认值：** `"system"`
#### `appearance.strict`
当为 `true` 时，隐藏浅色/深色模式切换。
**类型：** boolean
**默认值：** `false`
***
### `fonts`
自定义字体。支持 [Google Fonts](https://fonts.google.com) 和自托管字体。
**类型：** object
#### `fonts.family`
必需（使用 `fonts` 时）
字体系列名称。Google Fonts 系列名称会自动加载。
**类型：** string
#### `fonts.weight`
字体粗细。可变字体支持小数值如 `550`。
**类型：** number
#### `fonts.source`
托管字体的 URL 或本地字体文件的路径。Google Fonts 不需要此项。
**类型：** string (uri)
#### `fonts.format`
字体文件格式。使用 `fonts.source` 时必需。
**类型：** `"woff"` | `"woff2"`
***
### `icons`
图标库设置。
**类型：** object
#### `icons.library`
必需
在整个文档中使用的图标库。文档中的所有图标名称必须来自所选的图标库。
**类型：** `"fontawesome"` | `"lucide"` | `"tabler"`
**默认值：** `"fontawesome"`
***
### `background`
背景图片、装饰和颜色设置。
**类型：** object
#### `background.decoration`
装饰性背景图案。
**类型：** `"gradient"` | `"grid"` | `"windows"`
***
### `styling`
视觉样式控制。
**类型：** object
#### `styling.eyebrows`
页面 eyebrow 样式，显示在页面顶部。
**类型：** `"section"` | `"breadcrumbs"`
**默认值：** `"section"`
#### `styling.latex`
是否加载 LaTeX 样式表。默认情况下，Mintlify 会自动检测 LaTeX 使用。
**类型：** boolean
#### `styling.codeblocks`
代码块主题配置。
**类型：** `"system"` | `"dark"` | string (Shiki 主题名) | object
**默认值：** `"system"`
***
### `navbar`
顶部导航栏配置。
**类型：** object
#### `navbar.links`
导航栏中显示的链接。
**类型：** object 数组
#### `navbar.primary`
导航栏中的主要行动号召按钮。
**类型：** object
***
### `footer`
页脚内容和社交链接。
**类型：** object
#### `footer.socials`
社交媒体资料。每个键是平台名称，每个值是你的资料 URL。
**类型：** object
**有效键：** `x`、`website`、`facebook`、`youtube`、`discord`、`slack`、`github`、`linkedin`、`instagram`、`hacker-news`、`medium`、`telegram`、`twitter`、`x-twitter`、`earth-americas`、`bluesky`、`threads`、`reddit`、`podcast`
#### `footer.links`
页脚中的链接列。最多 4 列。
**类型：** object 数组（最多 4 个）
***
### `banner`
显示在每个页面顶部的全站横幅。
**类型：** object
#### `banner.content`
必需（使用 `banner` 时）
横幅文本。支持基本 MDX 格式，包括链接、粗体和斜体。不支持自定义组件。
**类型：** string
#### `banner.dismissible`
是否显示关闭按钮。
**类型：** boolean
**默认值：** `false`
#### `banner.type`
横幅背景的视觉样式。使用 `info` 表示常规公告，`warning` 表示警示性通知，`critical` 表示紧急问题。
**类型：** `"info"` | `"warning"` | `"critical"`
**默认值：** `"info"`
#### `banner.color`
自定义背景颜色覆盖。优先于 `type`。横幅文本为白色，因此请选择能保持可读性的背景。
**类型：** 包含 `light`（string）和 `dark`（string）十六进制值的 object，或应用于两种模式的单个十六进制字符串。
***
### `interaction`
导航交互设置。
**类型：** object
#### `interaction.drilldown`
控制用户点击导航组时的自动导航。设置为 `true` 会在用户点击组时导航到第一个页面，`false` 仅展开/折叠组而不导航。
**类型：** boolean
**默认值：** 主题默认
***
### `contextual`
页面操作和 AI 工具集成的上下文菜单。
**类型：** object
#### `contextual.options`
必需
上下文菜单中可用的操作。第一项是默认操作。
**类型：** `"assistant"` | `"copy"` | `"view"` | `"download-pdf"` | `"chatgpt"` | `"claude"` | `"perplexity"` | `"grok"` | `"aistudio"` | `"devin"` | `"devin-desktop"` | `"mcp"` | `"add-mcp"` | `"cursor"` | `"vscode"` | `"devin-mcp"` | object 的数组
#### `contextual.display`
显示上下文菜单的位置。
**类型：** `"header"` | `"toc"`
**默认值：** `"header"`
***
### `redirects`
已移动、重命名或删除页面的重定向。
**类型：** object 数组
***
### `variables`
使用 `{{variableName}}` 语法在构建时替换的全局内容变量。
**类型：** object—键是变量名（仅限字母数字和连字符），值是替换字符串。
***
### `metadata`
全局页面元数据设置。
**类型：** object
#### `metadata.timestamp`
在所有页面上显示最后修改日期。对于由 GitHub 或 GitLab 支持的部署，日期反映最后一次修改页面源文件的 git 提交时间；当无法获取 git 提交日期时，将回退为最近一次部署的时间戳。
**类型：** boolean
**默认值：** `false`
***
### `errors`
错误页面设置。
**类型：** object
#### `errors.404`
404 "页面未找到" 错误页面的设置。
**类型：** object
***
### `api`
API 文档和演练场设置。
**类型：** object
#### `api.openapi`
OpenAPI 规范文件。
**类型：** string | string 数组 | 带有 `source` (string) 和 `directory` (string) 的 object
#### `api.asyncapi`
AsyncAPI 规范文件。
**类型：** string | string 数组 | 带有 `source` (string) 和 `directory` (string) 的 object
#### `api.playground`
交互式演练场设置。
**类型：** object
##### `api.playground.display`
演练场显示模式。
**类型：** `"interactive"` | `"simple"` | `"none"` | `"auth"`
**默认值：** `"interactive"`
##### `api.playground.proxy`
是否通过代理路由 API 请求。
**类型：** boolean
**默认值：** `true`
##### `api.playground.credentials`
当 `proxy` 为 `false` 时，是否在跨域请求中包含 cookies 和身份验证头。当 `proxy` 为 `true` 时无效。
**类型：** boolean
**默认值：** `false`
#### `api.params`
API 参数显示设置。
**类型：** object
##### `api.params.expanded`
是否默认展开所有参数。
**类型：** `"all"` | `"closed"`
**默认值：** `"closed"`
##### `api.params.post`
要在每个参数名称旁显示为 post 标签的 OpenAPI 规范字段键名。对于每个键，Mintlify 会从 schema 中读取相应的值并渲染为标签：字符串按字面渲染，`true` 渲染为键名，数字会被字符串化，数组会为每个元素渲染一个标签。`false`、`null`、空字符串和对象会被忽略。
**类型：** array of string
#### `api.examples`
代码示例设置。
**类型：** object
##### `api.examples.languages`
自动生成代码片段的语言。请参阅[支持的语言](/zh/api-playground/overview#all-supported-languages)。
**类型：** string 数组
##### `api.examples.defaults`
是否在示例中包含可选参数。
**类型：** `"required"` | `"all"`
**默认值：** `"all"`
##### `api.examples.prefill`
是否用规范示例值预填演练场字段。
**类型：** boolean
**默认值：** `false`
##### `api.examples.autogenerate`
是否从 API 规范生成代码示例。
**类型：** boolean
**默认值：** `true`
***
### `seo`
搜索引擎优化设置。
**类型：** object
#### `seo.indexing`
搜索引擎应索引哪些页面。
**类型：** `"navigable"` | `"all"`
**默认值：** `"navigable"`
#### `seo.metatags`
添加到每个页面的自定义 meta 标签。键值对。
**类型：** object
***
### `search`
搜索栏设置。
**类型：** object
#### `search.prompt`
搜索栏中的占位符文本。
**类型：** string
***
### `integrations`
第三方集成。
**类型：** object
| 属性 | 类型 | 必需字段 | 描述 |
| ------------------------------------ | ---------------------- | ---- | -------------------------------------- |
| `integrations.adobe.launchUrl` | string (uri) | 是 | Adobe Analytics launch URL。 |
| `integrations.amplitude.apiKey` | string | 是 | Amplitude API key。 |
| `integrations.clarity.projectId` | string | 是 | Microsoft Clarity 项目 ID。 |
| `integrations.clearbit.publicApiKey` | string | 是 | Clearbit 公开 API key。 |
| `integrations.fathom.siteId` | string | 是 | Fathom 站点 ID。 |
| `integrations.frontchat.snippetId` | string (最小 6) | 是 | Front 聊天代码片段 ID。 |
| `integrations.ga4.measurementId` | string (必须以 `G` 开头) | 是 | Google Analytics 4 测量 ID。 |
| `integrations.gtm.tagId` | string (必须以 `G` 开头) | 是 | Google Tag Manager 容器 ID。 |
| `integrations.heap.appId` | string | 是 | Heap 应用 ID。 |
| `integrations.hightouch.writeKey` | string | 是 | Hightouch write key。 |
| `integrations.hotjar.hjid` | string | 是 | Hotjar 站点 ID。 |
| `integrations.hotjar.hjsv` | string | 是 | Hotjar 脚本版本。 |
| `integrations.intercom.appId` | string (最小 6) | 是 | Intercom 应用 ID。 |
| `integrations.logrocket.appId` | string | 是 | LogRocket 应用 ID。 |
| `integrations.mixpanel.projectToken` | string | 是 | Mixpanel 项目 token。 |
| `integrations.pirsch.id` | string | 是 | Pirsch 站点 ID。 |
| `integrations.plausible.domain` | string | 是 | Plausible 域名。 |
| `integrations.posthog.apiKey` | string (必须以 `phc_` 开头) | 是 | PostHog API key。 |
| `integrations.segment.key` | string | 是 | Segment write key。 |
| `integrations.telemetry.enabled` | boolean | 否 | 启用 Mintlify 遥测。当为 `false` 时，反馈功能也会被禁用。 |