快速参考
完整属性参考
$ref
docs.json 的任何级别使用 $ref 将配置拆分到多个文件中。
类型： string—指向 .json 文件的相对文件路径
- 当
$ref解析为对象时，Mintlify 会将同一块中的兄弟键合并到引用内容之上，使这些键优先于引用中的匹配键。 - 当
$ref解析为非对象值（如数组）时，Mintlify 会忽略任何兄弟键。 - 被引用的文件可以包含自己的
$ref条目，路径相对于该文件解析。 - 路径必须保持在项目根目录内。循环引用会导致构建错误。
$ref 拆分配置了解示例。
theme - 必需
站点的布局主题。
类型： string
选项： mint、maple、palm、willow、linden、almond、aspen、sequoia、luma
请参阅主题获取预览。
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
请参阅导航获取完整文档。
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
导航分组中根页面的目录布局。递归继承；后代可以覆盖。参见目录列表。
类型： "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 和自托管字体。
类型： 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
自动生成代码片段的语言。请参阅支持的语言。
类型： 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"