settings.mdx

title	全局设置
description	使用 docs.json 配置你的 Mintlify 文档站点，该文件控制导航、外观和集成。
keywords	docs.json 配置 设置 mint.json

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

必需字段

你必须定义四个字段才能构建一个可用的站点。

字段	描述
name	你的项目或组织名称
theme	站点的布局主题
colors.primary	主品牌颜色，使用十六进制代码
navigation	你的内容结构

所有其他字段都是可选的。你可以在自定义和完善站点时逐步添加它们。

最小配置

为了获得最佳编辑体验，请在 docs.json 的顶部包含 $schema 引用。这将在大多数编辑器中启用自动补全、校验和内联文档。

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "你的项目名称",
  "colors": {
    "primary": "#ff0000"
  },
  "navigation": [
    {
      "group": "首页",
      "pages": ["index"]
    }
  ]
}

设置

自定义站点的视觉外观，包括主题、颜色、logo、favicon、字体和背景。 设计站点的信息架构和用户体验，包括导航栏、页脚、横幅、导航和重定向。 控制 API 文档的显示和行为，包括 OpenAPI 和 AsyncAPI 规范、API 演练场和代码示例。 将站点连接到第三方服务，用于分析、聊天等功能。 控制搜索引擎如何索引你的站点，包括 meta 标签、搜索和页面时间戳。 所有 `docs.json` 属性的完整参考。

## 使用 `$ref` 拆分配置

随着配置的增长，你可以使用 $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 文件，请按照以下步骤升级到 docs.json。

如果你还没有安装 [CLI](/zh/installation)，现在安装它：

<CodeGroup>

```bash npm
npm i -g mint
```

```bash yarn
yarn global add mint
```

```bash pnpm
pnpm add -g mint
```

</CodeGroup>

如果你已经安装了 CLI，确保它是最新版本：

```bash
mint update
```

在你的文档仓库中运行：

```bash
mint upgrade
```

此命令会从你现有的 `mint.json` 创建一个 `docs.json` 文件。检查生成的文件以确保所有设置正确。

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