# 全局设置 (/zh/organize/settings)
Related: [外观与品牌](/zh/organize/settings-appearance.md), [站点结构](/zh/organize/settings-structure.md), [API 设置](/zh/organize/settings-api.md), [集成](/zh/organize/settings-integrations.md), [SEO 和搜索](/zh/organize/settings-seo.md), [docs.json schema 参考](/zh/organize/settings-reference.md)
`docs.json` 文件是 Mintlify 文档站点的核心配置文件。它控制站点的全局设置，包括视觉品牌、导航结构、集成、API 设置等。可以把它看作站点的蓝图。
## 必需字段 [#必需字段]
你必须定义四个字段才能构建一个可用的站点。
| 字段 | 描述 |
| ---------------- | ------------------------------- |
| `name` | 你的项目或组织名称 |
| `theme` | 站点的布局[主题](/zh/customize/themes) |
| `colors.primary` | 主品牌颜色，使用十六进制代码 |
| `navigation` | 你的内容结构 |
所有其他字段都是可选的。你可以在自定义和完善站点时逐步添加它们。
## 最小配置 [#最小配置]
为了获得最佳编辑体验，请在 `docs.json` 的顶部包含 `$schema` 引用。这将在大多数编辑器中启用自动补全、校验和内联文档。
```json title="docs.json"
{
"$schema": "https://mintlify.com/docs.json",
"theme": "mint",
"name": "你的项目名称",
"colors": {
"primary": "#ff0000"
},
"navigation": {
"groups": [
{
"group": "首页",
"pages": ["index"]
}
]
}
}
```
## 设置 [#设置]
自定义站点的视觉外观，包括主题、颜色、logo、favicon、字体和背景。
设计站点的信息架构和用户体验，包括导航栏、页脚、横幅、导航和重定向。
控制 API 文档的显示和行为，包括 OpenAPI 和 AsyncAPI 规范、API 演练场和代码示例。
将站点连接到第三方服务，用于分析、聊天等功能。
控制搜索引擎如何索引你的站点，包括 meta 标签、搜索和页面时间戳。
所有 `docs.json` 属性的完整参考。
## 使用 `$ref` 拆分配置 [#使用-ref-拆分配置]
随着配置的增长，你可以使用 `$ref` 引用将 `docs.json` 拆分成更小的文件。每个引用指向一个独立的 JSON 文件，在构建时进行解析。
在 `docs.json` 中的任何位置添加一个带有相对文件路径的 `$ref` 属性。Mintlify 会将 `$ref` 对象替换为被引用文件的内容。
```json title="docs.json"
{
"$schema": "https://mintlify.com/docs.json",
"theme": "mint",
"name": "Acme Docs",
"colors": {
"primary": "#1a73e8"
},
"navigation": {
"$ref": "./config/navigation.json"
}
}
```
```json title="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 会忽略任何兄弟键。
```json title="docs.json"
{
"appearance": {
"$ref": "./config/appearance.json",
"strict": true
}
}
```
## 从 `mint.json` 升级 [#从-mintjson-升级]
如果你的项目使用已弃用的 `mint.json` 文件，请使用 [CLI](/zh/cli) 升级到 `docs.json`。
如果你还没有安装 [CLI](/zh/cli/install)，现在安装它：
npm
yarn
pnpm
```bash
npm i -g mint
```
```bash
yarn global add mint
```
```bash
pnpm add -g mint
```
如果你已经安装了 CLI，确保它是最新版本：
```bash
mint update
```
在你的文档仓库中运行：
```bash
mint dev
```
此命令会从你现有的 `mint.json` 创建一个 `docs.json` 文件。检查生成的文件以确保所有设置正确。
在确认 `docs.json` 配置正确后，你可以安全地删除旧的 `mint.json` 文件。