站点结构

使用 docs.json 文件中的这些设置来控制站点的信息架构和用户体验。修改导航栏、页脚、横幅、导航行为、上下文菜单、重定向和全局内容变量。

设置

类型： object 内容的导航结构。这是你使用组、标签页、下拉菜单、锚点等定义站点完整页面层次结构的地方。有关构建导航结构的完整文档，请参阅导航。

显示在所有页面和区域设置中的全局导航元素。

显示 navigation.global

tabs

object 数组

用于组织主要部分的顶级导航标签页。请参阅标签页。

显示 tabs

tab

string

必填

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

icon

string

要显示的图标。可选值：

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。

iconType

string

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

hidden

boolean

是否默认隐藏此标签页。

href

string (uri)

必填

标签页目标的 URL 或路径。

anchors

object 数组

在侧边栏中醒目显示的锚定链接。请参阅锚点。

显示 anchors

anchor

string

必填

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

icon

string

要显示的图标。可选值：

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。

iconType

string

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

color

object

锚点图标的自定义颜色。

显示 color

light

string

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

dark

string

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

hidden

boolean

是否默认隐藏此锚点。

href

string (uri)

必填

锚点目标的 URL 或路径。

dropdowns

object 数组

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

显示 dropdowns

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

icon

string

要显示的图标。可选值：

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。

iconType

string

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

hidden

boolean

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

href

string (uri)

必填

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

languages

object 数组

本地化站点的语言切换器配置。请参阅语言。

显示 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"

必填

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

default

boolean

是否为默认语言。

hidden

boolean

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

href

string (uri)

必填

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

versions

object 数组

多版本站点的版本切换器配置。请参阅版本。

显示 versions

version

string

必填

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

default

boolean

是否为默认版本。

hidden

boolean

是否默认隐藏此版本。

href

string (uri)

必填

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

products

object 数组

多产品站点的产品切换器。请参阅产品。

显示 products

product

string

必填

产品的显示名称。

description

string

产品描述。

icon

string

要显示的图标。可选值：

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。

iconType

string

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

多语言站点的语言切换器。除了导航结构外，每个条目还可以包含特定语言的 banner、footer 和 navbar 配置。

显示 navigation.languages

language

必填

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

default

boolean

是否为默认语言。

banner

object

特定语言的横幅配置。接受与顶级 banner 字段相同的选项。

footer

object

特定语言的页脚配置。接受与顶级 footer 字段相同的选项。

特定语言的导航栏配置。接受与顶级 navbar 字段相同的选项。

hidden

boolean

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

具有多个版本的站点的版本切换器。

显示 navigation.versions

default

boolean

设置为 true 使其成为默认版本。如果省略，数组中的第一个版本为默认版本。

tag

string

在选择器中显示在版本旁边的徽章标签。用于突出显示版本，如 "Latest"、"Recommended" 或 "Beta"。

顶级导航标签页。

侧边栏锚点。

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

多产品站点的产品切换器。

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

组成文档的各个页面。

导航分组中根页面的目录布局。设置后，具有 root 页面的分组会自动在页面内容下方显示其子页面列表。值通过导航树递归继承。后代可以覆盖。参见目录列表。

类型： object 显示在顶部导航栏中的链接和按钮。

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

显示 navbar.links

type

"github" | "discord"

可选链接类型。省略时为标准文本链接。设置为 github 可链接到 GitHub 仓库并显示其 star 数。设置为 discord 可链接到 Discord 服务器并显示其在线用户数。

label

string

链接文本。未设置 type 时必需。对于 github 和 discord 可选。如果省略，Mintlify 会从 API 数据生成标签。

href

string (uri)

必填

链接目标。必须是有效的外部 URL。对于 github，必须是 GitHub 仓库 URL。对于 discord，必须是 Discord 邀请 URL。

icon

string

要显示的图标。可选值：

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。

iconType

string

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

导航栏中的主要行动号召按钮。

显示 navbar.primary

type

"button" | "github" | "discord"

必填

按钮样式。选择 button 为标准按钮，github 为带 star 数的 GitHub 仓库链接，或 discord 为带在线用户数的 Discord 邀请。

label

string

按钮文本。当 type 为 button 时必需。对于 github 和 discord 可选。

href

string (uri)

必填

按钮目标。必须是外部 URL。对于 github，必须是 GitHub 仓库 URL。对于 discord，必须是 Discord 邀请 URL。

docs.json

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

类型： object 页脚内容和社交媒体链接。

footer.socials

object

要在页脚中显示的社交媒体资料。每个键是平台名称，每个值是你的资料 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.links

object 数组

显示在页脚中的链接列。最多 4 列。

显示 footer.links

header

string

列标题。最小长度：1。

items

object 数组

必填

要在列中显示的链接。

显示 items

label

string

必填

链接文本。最小长度：1。

href

string (uri)

必填

链接目标 URL。

docs.json

"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" }
      ]
    }
  ]
}

类型： object 显示在每个页面顶部的全站横幅。

banner.content

string

必填

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

"content": "我们刚刚发布了新功能。[了解更多](https://example.com)"

banner.dismissible

boolean

是否显示关闭按钮以便用户关闭横幅。默认为 false。

docs.json

"banner": {
  "content": "我们刚刚发布了新功能。[了解更多](https://example.com)",
  "dismissible": true
}

`interaction`

类型： object 控制导航元素的用户交互行为。

interaction.drilldown

boolean

控制选择导航组时的自动导航。设置为 true 可在组展开时自动导航到第一个页面。设置为 false 仅展开或折叠组而不导航。留空则使用主题的默认行为。

`contextual`

类型： object 上下文菜单让用户快速访问 AI 工具和页面操作。它出现在页面标题或目录侧边栏中。

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

contextual.options

array

必填

上下文菜单中可用的操作。数组中的第一个选项显示为默认操作。内置选项：

"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

将自定义选项定义为对象：

显示自定义选项

title

string

必填

自定义选项的显示标题。

description

string

必填

自定义选项的描述文本。

icon

string

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

href

string 或 object

必填

链接目标。可以是 URL 字符串或带有 base 和可选 query 参数的对象。可用占位符值：

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

contextual.display

"header" | "toc"

显示上下文选项的位置。选择 header 在页面顶部上下文菜单中显示，或选择 toc 在目录侧边栏中显示。默认为 header。

docs.json

"contextual": {
  "options": ["copy", "view", "chatgpt", "claude"],
  "display": "header"
}

`redirects`

类型： object 数组 用于已移动、重命名或删除页面的重定向。使用这些重定向在重新组织内容时保留链接。

redirects[].source

string

必填

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

redirects[].destination

string

必填

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

redirects[].permanent

boolean

如果为 true，发出永久重定向（308）。如果为 false，发出临时重定向（307）。默认为 true。

docs.json

"redirects": [
  {
    "source": "/old-page",
    "destination": "/new-page"
  },
  {
    "source": "/temp-redirect",
    "destination": "/destination",
    "permanent": false
  }
]

`errors`

类型： object 自定义错误页面设置。

errors.404

object

404 “页面未找到” 错误页面的设置。

显示 errors.404

redirect

boolean

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

title

string

404 页面的自定义标题。

description

string

404 页面的自定义描述。支持 MDX 格式，包括链接、粗体和斜体文本以及自定义组件。

docs.json

"errors": {
  "404": {
    "redirect": false,
    "title": "页面未找到",
    "description": "你要找的页面不存在。[返回首页](/)。"
  }
}

`variables`

类型： object 在整个文档中使用的全局变量。Mintlify 在构建时使用 {{variableName}} 语法替换占位符为定义的值。

variables.[variableName]

string

键值对，其中键是变量名，值是替换文本。

变量名可以包含字母数字字符和连字符。
你必须定义内容中引用的所有变量，否则构建会失败。
Mintlify 会对值进行清理以防止 XSS 攻击。

docs.json

"variables": {
  "version": "2.0.0",
  "api-url": "https://api.example.com"
}

在内容中，使用双大括号引用变量：

当前版本是 {{version}}。请求发送到 {{api-url}}。

`metadata`

类型： object 全局应用的页面级元数据设置。

metadata.timestamp

boolean

在所有页面上启用最后修改日期。启用后，页面会显示内容最后修改的日期。默认为 false。你可以使用 timestamp frontmatter 字段为单个页面覆盖此设置。详情请参阅页面。

docs.json

"metadata": {
  "timestamp": true
}

设置

`navigation` - 必需

`navbar`

`footer`

`banner`

`interaction`

`contextual`

`redirects`

`errors`

`variables`

`metadata`

​设置

​navigation - 必需

​navbar

​footer

​banner

​interaction

​contextual

​redirects

​errors

​variables

​metadata

设置

`navigation` - 必需

`navbar`

`footer`

`banner`

`interaction`

`contextual`

`redirects`

`errors`

`variables`

`metadata`