> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-docs-automation-github-pr-review.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 全局设置

> 使用 docs.json 配置你的 Mintlify 文档站点，该文件控制导航、外观和集成。

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

## 必需字段

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

| 字段               | 描述                              |
| ---------------- | ------------------------------- |
| `name`           | 你的项目或组织名称                       |
| `theme`          | 站点的布局[主题](/zh/customize/themes) |
| `colors.primary` | 主品牌颜色，使用十六进制代码                  |
| `navigation`     | 你的内容结构                          |

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

## 最小配置

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

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

## 设置

<CardGroup cols={2}>
  <Card title="外观与品牌" icon="palette" href="/zh/organize/settings-appearance">
    自定义站点的视觉外观，包括主题、颜色、logo、favicon、字体和背景。
  </Card>

  <Card title="站点结构" icon="layout-panel-left" href="/zh/organize/settings-structure">
    设计站点的信息架构和用户体验，包括导航栏、页脚、横幅、导航和重定向。
  </Card>

  <Card title="API 设置" icon="square-terminal" href="/zh/organize/settings-api">
    控制 API 文档的显示和行为，包括 OpenAPI 和 AsyncAPI 规范、API 演练场和代码示例。
  </Card>

  <Card title="集成" icon="plug" href="/zh/organize/settings-integrations">
    将站点连接到第三方服务，用于分析、聊天等功能。
  </Card>

  <Card title="SEO 和搜索" icon="search" href="/zh/organize/settings-seo">
    控制搜索引擎如何索引你的站点，包括 meta 标签、搜索和页面时间戳。
  </Card>

  <Card title="Schema 参考" icon="code" href="/zh/organize/settings-reference">
    所有 `docs.json` 属性的完整参考。
  </Card>
</CardGroup>

<div id="split-configuration-with-ref">
  ## 使用 `$ref` 拆分配置
</div>

随着配置的增长，你可以使用 `$ref` 引用将 `docs.json` 拆分成更小的文件。每个引用指向一个独立的 JSON 文件，在构建时进行解析。

在 `docs.json` 中的任何位置添加一个带有相对文件路径的 `$ref` 属性。Mintlify 会将 `$ref` 对象替换为被引用文件的内容。

```json docs.json theme={null}
{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Acme Docs",
  "colors": {
    "primary": "#1a73e8"
  },
  "navigation": {
    "$ref": "./config/navigation.json"
  }
}
```

```json config/navigation.json theme={null}
{
  "groups": [
    {
      "group": "Get started",
      "pages": ["index", "quickstart"]
    },
    {
      "group": "Guides",
      "pages": ["guides/first-steps", "guides/advanced"]
    }
  ]
}
```

* 被引用的文件可以包含自己的 `$ref` 引用。嵌套路径相对于包含它们的文件解析，而不是相对于 `docs.json`。
* 引用必须指向有效的 JSON 文件。
* 路径必须是相对路径，且保持在项目根目录内。不允许路径遍历（例如 `../../outside`）。
* 循环引用会导致构建错误。

<div id="merging-sibling-keys">
  ### 合并兄弟键
</div>

如果 `$ref` 解析为对象，Mintlify 会将同一块中的兄弟键合并到引用内容之上，使这些键优先于引用中的匹配键。如果 `$ref` 解析为非对象值（如数组），Mintlify 会忽略任何兄弟键。

```json docs.json theme={null}
{
  "appearance": {
    "$ref": "./config/appearance.json",
    "strict": true
  }
}
```

## 从 `mint.json` 升级

如果你的项目使用已弃用的 `mint.json` 文件，请使用 [CLI](/zh/cli) 升级到 `docs.json`。

<Steps>
  <Step title="安装或更新 CLI">
    如果你还没有安装 [CLI](/zh/cli/install)，现在安装它：

    <CodeGroup>
      ```bash npm theme={null}
      npm i -g mint
      ```

      ```bash yarn theme={null}
      yarn global add mint
      ```

      ```bash pnpm theme={null}
      pnpm add -g mint
      ```
    </CodeGroup>

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

    ```bash theme={null}
    mint update
    ```
  </Step>

  <Step title="创建你的 docs.json 文件">
    在你的文档仓库中运行：

    ```bash theme={null}
    mint dev
    ```

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

  <Step title="删除你的 mint.json 文件">
    在确认 `docs.json` 配置正确后，你可以安全地删除旧的 `mint.json` 文件。
  </Step>
</Steps>