站点结构
在 docs.json 中配置导航栏、页脚、横幅、重定向和其他结构设置。
使用 docs.json 文件中的这些设置来控制站点的信息架构和用户体验。修改导航栏、页脚、横幅、导航行为、上下文菜单、重定向和全局内容变量。
设置
navigation - 必需
类型： object
内容的导航结构。这是你使用组、标签页、下拉菜单、锚点等定义站点完整页面层次结构的地方。
有关构建导航结构的完整文档，请参阅导航。
navigation.globalobject显示在所有页面和区域设置中的全局导航元素。
Show Hide navigation.global
tabsobject 数组用于组织主要部分的顶级导航标签页。请参阅标签页。
Show Hide tabs
tabstringrequired标签页的显示名称。最小长度：1。
iconstring要显示的图标。
可选值：
- Font Awesome 图标名称 (如果你在
docs.json中将icons.library属性 设置为fontawesome) - Lucide 图标名称 (如果你在
docs.json中将icons.library属性 设置为lucide) - Tabler 图标名称 (如果你在
docs.json中将icons.library属性 设置为tabler) - 指向外部托管图标的 URL
- 项目中图标文件的路径
- 用花括号包裹的 SVG 代码
对于自定义 SVG 图标：
- 使用 SVGR 转换器 转换你的 SVG。
- 将 SVG 代码粘贴到 SVG 输入框。
- 从 JSX 输出框中复制完整的
<svg>...</svg>元素。 - 用花括号包裹可用于 JSX 的 SVG 代码：
icon={<svg ...> ... </svg>}。 - 根据需要调整
height和width。
iconTypestringFont Awesome 的图标样式。仅在使用 Font Awesome 图标时生效。
可选值：regular、solid、light、thin、sharp-solid、duotone、brands。
hiddenboolean是否默认隐藏此标签页。
hrefstring (uri)required标签页目标的 URL 或路径。
anchorsobject 数组在侧边栏中醒目显示的锚定链接。请参阅锚点。
Show Hide anchors
anchorstringrequired锚点的显示名称。最小长度：1。
iconstring要显示的图标。
可选值：
- Font Awesome 图标名称 (如果你在
docs.json中将icons.library属性 设置为fontawesome) - Lucide 图标名称 (如果你在
docs.json中将icons.library属性 设置为lucide) - Tabler 图标名称 (如果你在
docs.json中将icons.library属性 设置为tabler) - 指向外部托管图标的 URL
- 项目中图标文件的路径
- 用花括号包裹的 SVG 代码
对于自定义 SVG 图标：
- 使用 SVGR 转换器 转换你的 SVG。
- 将 SVG 代码粘贴到 SVG 输入框。
- 从 JSX 输出框中复制完整的
<svg>...</svg>元素。 - 用花括号包裹可用于 JSX 的 SVG 代码：
icon={<svg ...> ... </svg>}。 - 根据需要调整
height和width。
iconTypestringFont Awesome 的图标样式。仅在使用 Font Awesome 图标时生效。
可选值：regular、solid、light、thin、sharp-solid、duotone、brands。
colorobject锚点图标的自定义颜色。
Show Hide color
lightstring浅色模式的锚点颜色。必须是以 # 开头的十六进制代码。
darkstring深色模式的锚点颜色。必须是以 # 开头的十六进制代码。
hiddenboolean是否默认隐藏此锚点。
hrefstring (uri)required锚点目标的 URL 或路径。
dropdownsobject 数组用于组织相关内容的下拉菜单。请参阅下拉菜单。
Show Hide dropdowns
dropdownstringrequired下拉菜单的显示名称。最小长度：1。
iconstring要显示的图标。
可选值：
- Font Awesome 图标名称 (如果你在
docs.json中将icons.library属性 设置为fontawesome) - Lucide 图标名称 (如果你在
docs.json中将icons.library属性 设置为lucide) - Tabler 图标名称 (如果你在
docs.json中将icons.library属性 设置为tabler) - 指向外部托管图标的 URL
- 项目中图标文件的路径
- 用花括号包裹的 SVG 代码
对于自定义 SVG 图标：
- 使用 SVGR 转换器 转换你的 SVG。
- 将 SVG 代码粘贴到 SVG 输入框。
- 从 JSX 输出框中复制完整的
<svg>...</svg>元素。 - 用花括号包裹可用于 JSX 的 SVG 代码：
icon={<svg ...> ... </svg>}。 - 根据需要调整
height和width。
iconTypestringFont Awesome 的图标样式。仅在使用 Font Awesome 图标时生效。
可选值：regular、solid、light、thin、sharp-solid、duotone、brands。
hiddenboolean是否默认隐藏此下拉菜单。
hrefstring (uri)required下拉菜单目标的 URL 或路径。
languagesobject 数组本地化站点的语言切换器配置。请参阅语言。
Show Hide languages
language"ar" | "ca" | "cn" | "cs" | "de" | "en" | "es" | "fi" | "fr" | "fr-CA" | "he" | "hi" | "hu" | "id" | "it" | "ja" | "ja-JP" | "jp" | "ko" | "lv" | "nl" | "no" | "pl" | "pt" | "pt-BR" | "ro" | "ru" | "sv" | "tr" | "uk" | "uz" | "vi" | "zh" | "zh-CN" | "zh-Hans" | "zh-Hant" | "zh-TW"requiredISO 639-1 格式的语言代码。
defaultboolean是否为默认语言。
hiddenboolean是否默认隐藏此语言选项。
hrefstring (uri)required指向文档此语言版本的有效路径或外部链接。
versionsobject 数组多版本站点的版本切换器配置。请参阅版本。
Show Hide versions
versionstringrequired版本的显示名称。最小长度：1。
defaultboolean是否为默认版本。
hiddenboolean是否默认隐藏此版本。
hrefstring (uri)required指向文档此版本的 URL 或路径。
productsobject 数组多产品站点的产品切换器。请参阅产品。
Show Hide products
productstringrequired产品的显示名称。
descriptionstring产品描述。
iconstring要显示的图标。
可选值：
- Font Awesome 图标名称 (如果你在
docs.json中将icons.library属性 设置为fontawesome) - Lucide 图标名称 (如果你在
docs.json中将icons.library属性 设置为lucide) - Tabler 图标名称 (如果你在
docs.json中将icons.library属性 设置为tabler) - 指向外部托管图标的 URL
- 项目中图标文件的路径
- 用花括号包裹的 SVG 代码
对于自定义 SVG 图标：
- 使用 SVGR 转换器 转换你的 SVG。
- 将 SVG 代码粘贴到 SVG 输入框。
- 从 JSX 输出框中复制完整的
<svg>...</svg>元素。 - 用花括号包裹可用于 JSX 的 SVG 代码：
icon={<svg ...> ... </svg>}。 - 根据需要调整
height和width。
iconTypestringFont Awesome 的图标样式。仅在使用 Font Awesome 图标时生效。
可选值：regular、solid、light、thin、sharp-solid、duotone、brands。
navigation.languagesobject 数组多语言站点的语言切换器。除了导航结构外，每个条目还可以包含特定语言的 banner、footer 和 navbar 配置。
Show Hide navigation.languages
language"ar" | "ca" | "cn" | "cs" | "de" | "en" | "es" | "fi" | "fr" | "fr-CA" | "he" | "hi" | "hu" | "id" | "it" | "ja" | "ja-JP" | "jp" | "ko" | "lv" | "nl" | "no" | "pl" | "pt" | "pt-BR" | "ro" | "ru" | "sv" | "tr" | "uk" | "uz" | "vi" | "zh" | "zh-CN" | "zh-Hans" | "zh-Hant" | "zh-TW"requiredISO 639-1 格式的语言代码。
defaultboolean是否为默认语言。
bannerobject特定语言的横幅配置。接受与顶级 banner 字段相同的选项。
footerobject特定语言的页脚配置。接受与顶级 footer 字段相同的选项。
navbarobject特定语言的导航栏配置。接受与顶级 navbar 字段相同的选项。
hiddenboolean是否默认隐藏此语言选项。
navigation.versionsobject 数组具有多个版本的站点的版本切换器。
Show Hide navigation.versions
defaultboolean设置为 true 使其成为默认版本。如果省略，数组中的第一个版本为默认版本。
tagstring在选择器中显示在版本旁边的徽章标签。用于突出显示版本，如 "Latest"、"Recommended" 或 "Beta"。
navigation.tabsobject 数组顶级导航标签页。
navigation.anchorsobject 数组侧边栏锚点。
navigation.dropdownsobject 数组用于分组相关内容的下拉菜单。
navigation.productsobject 数组多产品站点的产品切换器。
navigation.groupsobject 数组用于将内容组织成部分的组。
navigation.pagesstring 或 object 数组组成文档的各个页面。
navigation.directory"none" | "accordion" | "card"导航分组中根页面的目录布局。设置后，具有 root 页面的分组会自动在页面内容下方显示其子页面列表。值通过导航树递归继承。后代可以覆盖。参见目录列表。
navbar
类型： object
显示在顶部导航栏中的链接和按钮。
navbar.linksobject 数组要在导航栏中显示的链接。
Show Hide navbar.links
type"github" | "discord"可选链接类型。省略时为标准文本链接。设置为 github 可链接到 GitHub 仓库并显示其 star 数。设置为 discord 可链接到 Discord 服务器并显示其在线用户数。
labelstring链接文本。未设置 type 时必需。对于 github 和 discord 可选。如果省略，Mintlify 会从 API 数据生成标签。
hrefstring (uri)required链接目标。必须是有效的外部 URL。对于 github，必须是 GitHub 仓库 URL。对于 discord，必须是 Discord 邀请 URL。
iconstring要显示的图标。
可选值：
- Font Awesome 图标名称 (如果你在
docs.json中将icons.library属性 设置为fontawesome) - Lucide 图标名称 (如果你在
docs.json中将icons.library属性 设置为lucide) - Tabler 图标名称 (如果你在
docs.json中将icons.library属性 设置为tabler) - 指向外部托管图标的 URL
- 项目中图标文件的路径
- 用花括号包裹的 SVG 代码
对于自定义 SVG 图标：
- 使用 SVGR 转换器 转换你的 SVG。
- 将 SVG 代码粘贴到 SVG 输入框。
- 从 JSX 输出框中复制完整的
<svg>...</svg>元素。 - 用花括号包裹可用于 JSX 的 SVG 代码：
icon={<svg ...> ... </svg>}。 - 根据需要调整
height和width。
iconTypestringFont Awesome 的图标样式。仅在使用 Font Awesome 图标时生效。
可选值：regular、solid、light、thin、sharp-solid、duotone、brands。
navbar.primaryobject导航栏中的主要行动号召按钮。
Show Hide navbar.primary
type"button" | "github" | "discord"required按钮样式。选择 button 为标准按钮，github 为带 star 数的 GitHub 仓库链接，或 discord 为带在线用户数的 Discord 邀请。
labelstring按钮文本。当 type 为 button 时必需。对于 github 和 discord 可选。
hrefstring (uri)required按钮目标。必须是外部 URL。对于 github，必须是 GitHub 仓库 URL。对于 discord，必须是 Discord 邀请 URL。
"navbar": {
"links": [
{ "type": "github", "href": "https://github.com/your-org/your-repo" },
{ "label": "社区", "href": "https://example.com/community" }
],
"primary": {
"type": "button",
"label": "开始使用",
"href": "https://example.com/signup"
}
}footer
类型： object
页脚内容和社交媒体链接。
footer.socialsobject要在页脚中显示的社交媒体资料。每个键是平台名称，每个值是你的资料 URL。
有效键：x、website、facebook、youtube、discord、slack、github、linkedin、instagram、hacker-news、medium、telegram、twitter、x-twitter、earth-americas、bluesky、threads、reddit、podcast
"socials": {
"x": "https://x.com/yourhandle",
"github": "https://github.com/your-org"
}footer.linksobject 数组显示在页脚中的链接列。最多 4 列。
Show Hide footer.links
headerstring列标题。最小长度：1。
itemsobject 数组required要在列中显示的链接。
Show Hide items
labelstringrequired链接文本。最小长度：1。
hrefstring (uri)required链接目标 URL。
"footer": {
"socials": {
"x": "https://x.com/yourhandle",
"github": "https://github.com/your-org"
},
"links": [
{
"header": "公司",
"items": [
{ "label": "博客", "href": "https://example.com/blog" },
{ "label": "招聘", "href": "https://example.com/careers" }
]
}
]
}banner
类型： object
显示在每个页面顶部的全站横幅。
banner.contentstringrequired横幅中显示的文本内容。支持基本 MDX 格式，包括链接、粗体和斜体文本。不支持自定义组件。
"content": "我们刚刚发布了新功能。[了解更多](https://example.com)"banner.dismissibleboolean是否显示关闭按钮以便用户关闭横幅。默认为 false。
"banner": {
"content": "我们刚刚发布了新功能。[了解更多](https://example.com)",
"dismissible": true
}interaction
类型： object
控制导航元素的用户交互行为。
interaction.drilldownboolean控制选择导航组时的自动导航。设置为 true 可在组展开时自动导航到第一个页面。设置为 false 仅展开或折叠组而不导航。留空则使用主题的默认行为。
contextual
类型： object
上下文菜单让用户快速访问 AI 工具和页面操作。它出现在页面标题或目录侧边栏中。
上下文菜单仅在预览和生产部署中可用。
contextual.optionsarrayrequired上下文菜单中可用的操作。数组中的第一个选项显示为默认操作。
内置选项：
"add-mcp"—将你的 MCP 服务器添加到用户的配置中"aistudio"—将当前页面发送到 Google AI Studio"assistant"—以当前页面为上下文打开 AI 助手"copy"—将当前页面复制为 Markdown 到剪贴板"chatgpt"—将当前页面发送到 ChatGPT"claude"—将当前页面发送到 Claude"cursor"—在 Cursor 中安装你托管的 MCP 服务器"devin"—将当前页面发送到 Devin"devin-mcp"—在 Devin 中安装你托管的 MCP 服务器"download-pdf"—将当前页面下载为 PDF"grok"—将当前页面发送到 Grok"mcp"—将你的 MCP 服务器 URL 复制到剪贴板"perplexity"—将当前页面发送到 Perplexity"view"—在新标签页中以 Markdown 查看当前页面"vscode"—在 VS Code 中安装你托管的 MCP 服务器"devin-desktop"—以当前页面为上下文打开 Devin Desktop
将自定义选项定义为对象：
Show Hide 自定义选项
titlestringrequired自定义选项的显示标题。
descriptionstringrequired自定义选项的描述文本。
iconstring自定义选项的图标。支持图标库名称、URL、路径或 SVG 代码。
hrefstring 或 objectrequired链接目标。可以是 URL 字符串或带有 base 和可选 query 参数的对象。
可用占位符值：
$page—当前页面内容$path—当前页面路径$mcp—MCP 服务器 URL
contextual.display"header" | "toc"显示上下文选项的位置。选择 header 在页面顶部上下文菜单中显示，或选择 toc 在目录侧边栏中显示。默认为 header。
"contextual": {
"options": ["copy", "view", "chatgpt", "claude"],
"display": "header"
}redirects
类型： object 数组
用于已移动、重命名或删除页面的重定向。使用这些重定向在重新组织内容时保留链接。
redirects[].sourcestringrequired要重定向的源路径。示例：/old-page
redirects[].destinationstringrequired要重定向到的目标路径。示例：/new-page
redirects[].permanentboolean如果为 true，发出永久重定向（308）。如果为 false，发出临时重定向（307）。默认为 true。
"redirects": [
{
"source": "/old-page",
"destination": "/new-page"
},
{
"source": "/temp-redirect",
"destination": "/destination",
"permanent": false
}
]errors
类型： object
自定义错误页面设置。
errors.404object404 “页面未找到” 错误页面的设置。
Show Hide errors.404
redirectboolean当找不到页面时是否自动重定向到首页。默认为 true。
titlestring404 页面的自定义标题。
descriptionstring404 页面的自定义描述。支持 MDX 格式，包括链接、粗体和斜体文本以及自定义组件。
"errors": {
"404": {
"redirect": false,
"title": "页面未找到",
"description": "你要找的页面不存在。[返回首页](/)。"
}
}variables
类型： object
在整个文档中使用的全局变量。Mintlify 在构建时使用 {{variableName}} 语法替换占位符为定义的值。
variables.[variableName]string键值对，其中键是变量名，值是替换文本。
- 变量名可以包含字母数字字符和连字符。
- 你必须定义内容中引用的所有变量，否则构建会失败。
- Mintlify 会对值进行清理以防止 XSS 攻击。
"variables": {
"version": "2.0.0",
"api-url": "https://api.example.com"
}在内容中，使用双大括号引用变量：
当前版本是 {{version}}。请求发送到 {{api-url}}。metadata
类型： object
全局应用的页面级元数据设置。
metadata.timestampboolean在所有页面上启用最后修改日期。启用后，页面会显示内容最后修改的日期。默认为 false。
你可以使用 timestamp frontmatter 字段为单个页面覆盖此设置。详情请参阅页面。
"metadata": {
"timestamp": true
}