跳转到主要内容
docs.json 文件是 Mintlify 文档站点的核心配置文件。它控制站点的全局设置，包括视觉品牌、导航结构、集成、API 设置等。可以把它看作站点的蓝图。

​
必需字段

你必须定义四个字段才能构建一个可用的站点。
字段描述
name你的项目或组织名称
theme站点的布局主题
colors.primary主品牌颜色，使用十六进制代码
navigation你的内容结构
所有其他字段都是可选的。你可以在自定义和完善站点时逐步添加它们。

​
最小配置

为了获得最佳编辑体验，请在 docs.json 的顶部包含 $schema 引用。这将在大多数编辑器中启用自动补全、校验和内联文档。
docs.json
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "你的项目名称",
  "colors": {
    "primary": "#ff0000"
  },
  "navigation": [
    {
      "group": "首页",
      "pages": ["index"]
    }
  ]
}

​
设置

外观与品牌

自定义站点的视觉外观，包括主题、颜色、logo、favicon、字体和背景。

站点结构

设计站点的信息架构和用户体验，包括导航栏、页脚、横幅、导航和重定向。

API 设置

控制 API 文档的显示和行为，包括 OpenAPI 和 AsyncAPI 规范、API 演练场和代码示例。

集成

将站点连接到第三方服务，用于分析、聊天等功能。

SEO 和搜索

控制搜索引擎如何索引你的站点，包括 meta 标签、搜索和页面时间戳。

Schema 参考

所有 docs.json 属性的完整参考。

​
使用 $ref 拆分配置

随着配置的增长，你可以使用 $ref 引用将 docs.json 拆分成更小的文件。每个引用指向一个独立的 JSON 文件，在构建时进行解析。 在 docs.json 中的任何位置添加一个带有相对文件路径的 $ref 属性。Mintlify 会将 $ref 对象替换为被引用文件的内容。
docs.json
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Acme Docs",
  "colors": {
    "primary": "#1a73e8"
  },
  "navigation": {
    "$ref": "./config/navigation.json"
  }
}
config/navigation.json
[
  {
    "group": "Get started",
    "pages": ["index", "quickstart"]
  },
  {
    "group": "Guides",
    "pages": ["guides/first-steps", "guides/advanced"]
  }
]
  • 被引用的文件可以包含自己的 $ref 引用。嵌套路径相对于包含它们的文件解析，而不是相对于 docs.json。
  • 引用必须指向有效的 JSON 文件。
  • 路径必须是相对路径，且保持在项目根目录内。不允许路径遍历（例如 ../../outside）。
  • 循环引用会导致构建错误。

​
合并兄弟键

如果 $ref 解析为对象，Mintlify 会将同一块中的兄弟键合并到引用内容之上，使这些键优先于引用中的匹配键。如果 $ref 解析为非对象值（如数组），Mintlify 会忽略任何兄弟键。
docs.json
{
  "appearance": {
    "$ref": "./config/appearance.json",
    "strict": true
  }
}

​
从 mint.json 升级

如果你的项目使用已弃用的 mint.json 文件，请按照以下步骤升级到 docs.json。
1

安装或更新 CLI

如果你还没有安装 CLI，现在安装它：
npm i -g mint
如果你已经安装了 CLI，确保它是最新版本：
mint update
2

创建你的 docs.json 文件

在你的文档仓库中运行：
mint upgrade
此命令会从你现有的 mint.json 创建一个 docs.json 文件。检查生成的文件以确保所有设置正确。
3

删除你的 mint.json 文件

在确认 docs.json 配置正确后，你可以安全地删除旧的 mint.json 文件。