全局设置

每个 Mintlify 站点都需要一个 docs.json 文件来承载核心配置。下面介绍常用属性（properties）。

属性（Properties）

string

required

项目名称，用于全局标题（global title）。示例：mintlify

分组数组，每个分组包含该组内的页面

Show Navigation

string

分组名称。示例：Settings

string[]

作为页面渲染的 Markdown 文件相对路径。示例：["customization", "page"]

string or object

Logo 图片路径，或包含「light / dark」两套 logo 路径的对象

Show Logo

string

浅色模式下的 logo 路径

string

深色模式下的 logo 路径

string

default:"/"

点击 logo 后跳转到的链接

string

favicon 图片路径

Colors

全局主题配色（Hex color）

Show Colors

string

required

主色（primary）。浅色模式下主要用于高亮内容、分节标题、强调色等。

string

深色模式下的主色（primary）。主要用于高亮内容、分节标题、强调色等。

string

重要按钮的主色

object

浅色/深色模式的背景色

Show Object

string

required

浅色模式背景色（Hex）

string

required

深色模式背景色（Hex）

TopbarLink[]

顶部栏（topbar）链接数组，由 name 与 url 组成

Show TopbarLink

string

按钮名称。示例：Contact us

string

点击按钮后的跳转 URL。示例：https://mintlify.com/docs

Call to Action

Show Topbar Call to Action

"link" or "github"

default:"link"

link：显示一个按钮；github：根据提供的仓库 URL 展示 GitHub 信息（含 star 数）。

string

若为 link：按钮跳转到的 URL。若为 github：用于加载 GitHub 信息的仓库链接。

string

按钮文字。仅当 type 为 link 时必填。

string[]

版本名称数组。仅当你希望在导航栏中用下拉框展示多版本文档时使用。

Anchor[]

anchors 数组，包含 icon、color、url 等配置。

Show Anchor

string

用于展示该 anchor 的 Font Awesome icon。示例：comments

string

anchor 的显示名称（label）。示例：Community

string

URL 前缀，用于标识哪些页面归入该 anchor。一般对应你放置页面的文件夹名称。

string

anchor icon 背景色（Hex）。也可传入包含 from 和 to（均为 Hex）的对象来实现渐变。

string

若你希望在选择特定文档版本前隐藏该 anchor，可使用此字段。

boolean

default:"false"

传 true 则默认隐藏该 anchor，直到你使用直链把用户带到该 anchor 下的页面。

string

default:"duotone"

可选值之一：“brands”、“duotone”、“light”、“sharp-solid”、“solid”、“thin”

Object

覆盖最顶部 anchor 的默认配置。

Show Object

string

default:"Documentation"

最顶部 anchor 的名称

string

default:"book-open"

Font Awesome icon。

string

default:"duotone"

可选值之一：“brands”、“duotone”、“light”、“sharp-solid”、“solid”、“thin”

Tabs[]

导航 tabs 数组。

Show Tabs

string

tab 的显示名称（label）。

string

URL 前缀，用于标识哪些页面归入该 tab。一般对应你放置页面的文件夹名称。

API

API 相关配置。更多信息可参考 Mintlify API Playground 概览。

Show API

string

所有 API endpoints 的 base URL。若 baseUrl 为数组，则会启用多个可切换的 base URL 选项。

Auth

Show Auth

"bearer" | "basic" | "key"

所有 API endpoints 使用的鉴权策略。

string

API playground 中使用的鉴权参数名称。若 method 为 basic，格式应为 [usernameName]:[passwordName]

string

设计为鉴权输入框前缀的默认值。例如：若 inputPrefix 为 AuthKey，则鉴权输入框会默认以 AuthKey 作为前缀。

Playground

API playground 配置

Show Playground

"show" | "simple" | "hide"

default:"show"

playground 的展示模式：显示（show）、隐藏（hide）、或仅展示 endpoint 但不提供交互的简化模式（simple）。更多说明见：Mintlify API Playground 概览

boolean

启用该开关后，OpenAPI 页面中的 key 顺序会与 OpenAPI 文件中定义的顺序一致。

This behavior will soon be enabled by default, at which point this field will be deprecated.

string | string[]

指向 OpenAPI 文件的 URL（字符串）或 URL 数组（字符串数组），也可以使用相对路径。示例：

"openapi": "https://example.com/openapi.json"

"openapi": "/openapi.json"

"openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"]

FooterSocials

社交媒体账号对象，其中 key 表示平台、value 表示账号 URL。示例：

{
  "x": "https://x.com/mintlify",
  "website": "https://mintlify.com"
}

Show FooterSocials

string

可选值之一：website、facebook、x、discord、slack、github、linkedin、instagram、hacker-news示例：x

string

对应平台的 URL。示例：https://x.com/mintlify

Feedback

反馈（feedback）按钮相关配置

Show Feedback

boolean

default:"false"

启用按钮，允许用户通过 Pull Request 提交修改建议

boolean

default:"false"

启用按钮，允许用户针对文档提出 Issue

ModeToggle

自定义深色模式切换（dark mode toggle）。

Show ModeToggle

"light" or "dark"

为新用户设置默认展示 light 或 dark 模式。未设置时，默认跟随用户操作系统。

boolean

default:"false"

设为 true 可隐藏 light/dark 模式切换。你也可以将 isHidden 与 default 组合使用，强制文档只使用 light 或 dark 模式。例如：

"modeToggle": {
  "default": "dark",
  "isHidden": true
}

"modeToggle": {
  "default": "light",
  "isHidden": true
}

string

显示在每个页面背后的背景图。可参考示例：Infisical 以及 FRPC。

工作流

Mintlify 写法

属性（Properties）

​属性（Properties）

属性（Properties）