mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
a8e0267c50
Generated-By: mintlify-agent Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
168 lines
4.9 KiB
Plaintext
168 lines
4.9 KiB
Plaintext
---
|
||
title: "全局设置"
|
||
description: "使用 docs.json 配置你的 Mintlify 文档站点，该文件控制导航、外观和集成。"
|
||
keywords: ["docs.json", "配置", "设置", "mint.json"]
|
||
---
|
||
|
||
`docs.json` 文件是 Mintlify 文档站点的核心配置文件。它控制站点的全局设置，包括视觉品牌、导航结构、集成、API 设置等。可以把它看作站点的蓝图。
|
||
|
||
## 必需字段
|
||
|
||
你必须定义四个字段才能构建一个可用的站点。
|
||
|
||
| 字段 | 描述 |
|
||
|---|---|
|
||
| `name` | 你的项目或组织名称 |
|
||
| `theme` | 站点的布局[主题](/zh/customize/themes) |
|
||
| `colors.primary` | 主品牌颜色，使用十六进制代码 |
|
||
| `navigation` | 你的内容结构 |
|
||
|
||
所有其他字段都是可选的。你可以在自定义和完善站点时逐步添加它们。
|
||
|
||
## 最小配置
|
||
|
||
为了获得最佳编辑体验，请在 `docs.json` 的顶部包含 `$schema` 引用。这将在大多数编辑器中启用自动补全、校验和内联文档。
|
||
|
||
```json docs.json
|
||
{
|
||
"$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
|
||
{
|
||
"$schema": "https://mintlify.com/docs.json",
|
||
"theme": "mint",
|
||
"name": "Acme Docs",
|
||
"colors": {
|
||
"primary": "#1a73e8"
|
||
},
|
||
"navigation": {
|
||
"$ref": "./config/navigation.json"
|
||
}
|
||
}
|
||
```
|
||
|
||
```json config/navigation.json
|
||
{
|
||
"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
|
||
{
|
||
"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
|
||
npm i -g mint
|
||
```
|
||
|
||
```bash yarn
|
||
yarn global add mint
|
||
```
|
||
|
||
```bash pnpm
|
||
pnpm add -g mint
|
||
```
|
||
|
||
</CodeGroup>
|
||
|
||
如果你已经安装了 CLI，确保它是最新版本：
|
||
|
||
```bash
|
||
mint update
|
||
```
|
||
</Step>
|
||
<Step title="创建你的 docs.json 文件">
|
||
在你的文档仓库中运行：
|
||
|
||
```bash
|
||
mint dev
|
||
```
|
||
|
||
此命令会从你现有的 `mint.json` 创建一个 `docs.json` 文件。检查生成的文件以确保所有设置正确。
|
||
</Step>
|
||
<Step title="删除你的 mint.json 文件">
|
||
在确认 `docs.json` 配置正确后，你可以安全地删除旧的 `mint.json` 文件。
|
||
</Step>
|
||
</Steps>
|