全局设置
使用 docs.json 配置你的 Mintlify 文档站点，该文件控制导航、外观和集成。
docs.json 文件是 Mintlify 文档站点的核心配置文件。它控制站点的全局设置，包括视觉品牌、导航结构、集成、API 设置等。可以把它看作站点的蓝图。
docs.json 位于你的文档仓库根目录，与内容文件放在一起。你可以在网页编辑器中编辑，也可以在仓库中使用你喜欢的 IDE 直接编辑。
必需字段
你必须定义四个字段才能构建一个可用的站点。
| 字段 | 描述 |
|---|---|
name | 你的项目或组织名称 |
theme | 站点的布局主题 |
colors.primary | 主品牌颜色，使用十六进制代码 |
navigation | 你的内容结构 |
所有其他字段都是可选的。你可以在自定义和完善站点时逐步添加它们。
最小配置
为了获得最佳编辑体验，请在 docs.json 的顶部包含 $schema 引用。这将在大多数编辑器中启用自动补全、校验和内联文档。
{
"$schema": "https://mintlify.com/docs.json",
"theme": "mint",
"name": "你的项目名称",
"colors": {
"primary": "#ff0000"
},
"navigation": {
"groups": [
{
"group": "首页",
"pages": ["index"]
}
]
}
}设置
随着配置的增长，你可以使用 $ref 引用将 docs.json 拆分成更小的文件。每个引用指向一个独立的 JSON 文件，在构建时进行解析。
在 docs.json 中的任何位置添加一个带有相对文件路径的 $ref 属性。Mintlify 会将 $ref 对象替换为被引用文件的内容。
{
"$schema": "https://mintlify.com/docs.json",
"theme": "mint",
"name": "Acme Docs",
"colors": {
"primary": "#1a73e8"
},
"navigation": {
"$ref": "./config/navigation.json"
}
}{
"groups": [
{
"group": "Get started",
"pages": ["index", "quickstart"]
},
{
"group": "Guides",
"pages": ["guides/first-steps", "guides/advanced"]
}
]
}- 被引用的文件可以包含自己的
$ref引用。嵌套路径相对于包含它们的文件解析，而不是相对于docs.json。 - 引用必须指向有效的 JSON 文件。
- 路径必须是相对路径，且保持在项目根目录内。不允许路径遍历（例如
../../outside）。 - 循环引用会导致构建错误。
如果 $ref 解析为对象，Mintlify 会将同一块中的兄弟键合并到引用内容之上，使这些键优先于引用中的匹配键。如果 $ref 解析为非对象值（如数组），Mintlify 会忽略任何兄弟键。
{
"appearance": {
"$ref": "./config/appearance.json",
"strict": true
}
}从 mint.json 升级
如果你的项目使用已弃用的 mint.json 文件，请使用 CLI 升级到 docs.json。
创建你的 docs.json 文件
在你的文档仓库中运行：
mint dev此命令会从你现有的 mint.json 创建一个 docs.json 文件。检查生成的文件以确保所有设置正确。
删除你的 mint.json 文件
在确认 docs.json 配置正确后，你可以安全地删除旧的 mint.json 文件。
Was this page helpful?Suggest editsRaise issue