> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync/content-configuration.md).

# 内容配置

通过代码配置 Git Sync

Git Sync 使用三个文件。请选择控制你所需 Git Sync 部分的文件：

* `gitbook-docs.yaml` 用于配置站点并将空间映射到存储库目录。
* `.gitbook.yaml` 用于配置 GitBook 如何读取单个空间的内容。
* `SUMMARY.md` 用于定义空间的导航。

### 使用 gitbook-docs.yaml 配置站点

`gitbook-docs.yaml` 用于配置整个站点。它位于 Git Sync 项目目录中。如果未设置 **项目目录**.

使用 `gitbook-docs.yaml` 定义站点结构，并将每个空间映射到一个目录。 `site.structure` 中的每一项都有一个稳定的 `key`。空间的 `content.directory` 用于设置其存储库目录。如果站点中的某个空间未同步到站点的存储库，其 `content.directory` 值为 `null`.

#### 了解站点和空间配置

`gitbook-docs.yaml` 负责管理站点级结构和目录映射。 `.gitbook.yaml` 用于配置某个映射空间的内容。

如果这两个文件都存在，GitBook 会先应用 `gitbook-docs.yaml` 以选择空间目录。 `.gitbook.yaml` 随后配置该目录中的内容。它无法覆盖站点级的 `content.directory` 映射。

#### 键用于标识你的空间

Git Sync 会通过空间和分区的 `key`来识别它们，而不是通过标题、路径或目录。GitBook 通过此键，将 `gitbook-docs.yaml` 中的条目与前一次同步中的现有内容进行匹配。

{% hint style="danger" %}
**更改空间的 `key` 会替换该空间。** GitBook 会将旧键视为已删除，并将新键视为一个新空间。它会创建一个新空间，从映射的目录中导入内容，并将原空间保留在你的组织中，使其与站点脱离关联。

你的页面会回来，但会出现在一个带有新空间 ID 的新空间中。引用旧 ID 的链接、卡片和 API 调用将停止解析，而任何只存在于 GitBook 而不在你的仓库中的内容都会保留在原始空间中。

恢复原始键也无法撤销这一点。它会创建另一个新空间，并将内容导入其中。
{% endhint %}

在首次创建条目时，可以自由选择键，而 GitBook 会在保存站点内容映射时为你生成键。一旦空间上线，就应将其键视为永久不变：

* 要重命名空间，请更改其 `title`。键保持不变。
* 要更改空间的 URL，请更改其 `path`。键保持不变。

此示例将英语和法语空间映射到不同的目录：

{% code title="gitbook-docs.yaml" expandable="true" %}

```yaml
$schema: https://api.gitbook.com/gitbook-docs.yaml
site:
  title: 文档
  structure:
    - type: section
      key: documentation
      title: 文档
      path: documentation
      children:
        - type: space
          key: docs-en
          title: 英文
          path: docs
          default: true
          content:
            directory: ./docs/en
            language: en
        - type: space
          key: docs-fr
          title: 法语
          path: fr
          content:
            directory: ./docs/fr
            language: fr
```

{% endcode %}

<details>

<summary>配置其他站点属性</summary>

使用这些可选属性来优化你的站点结构：

| 属性                     | 用途               |
| ---------------------- | ---------------- |
| `type: section-group`  | 将相关部分归入共享的导航标题下。 |
| `description`          | 为某个部分添加描述。       |
| `icon`                 | 为某个部分或部分组添加图标。   |
| `localizedTitle`       | 翻译某个部分、部分组或空间标题。 |
| `localizedDescription` | 翻译某个部分的描述。       |
| `hidden`               | 在站点导航中隐藏某个空间。    |

保存站点内容映射时，GitBook 会创建或更新 `gitbook-docs.yaml` 。

</details>

### 使用 .gitbook.yaml 配置空间

`.gitbook.yaml` 用于配置单个空间。它位于该空间映射到的目录中。使用它来设置内容根目录、首页、导航文件和重定向。

例如，当某个空间映射到 `./docs`时，请将该文件放在 `./docs/.gitbook.yaml` 并保留 `root: ./` ，除非内容还嵌套在更深的目录中。如果某个空间映射到仓库根目录，而其内容位于 `./docs`，请将 `.gitbook.yaml` 放在仓库根目录，并设置 `root: ./docs/`.

主要设置如下：

* `root` 用于设置 GitBook 读取的目录。默认值为 `./`.
* `structure.readme` 用于设置首页。默认值为 `README.md`.
* `structure.summary` 设置导航文件。默认值为 `SUMMARY.md`.
* `redirects` 将空间内的旧路径映射到新路径。

以下是一个典型配置：

{% code title=".gitbook.yaml" %}

```yaml
root: ./

structure:
  readme: README.md
  summary: SUMMARY.md

redirects:
  previous/page: new-folder/page.md
```

{% endcode %}

#### 设置内容根目录

当空间内容位于子目录中时，设置 `root` ：

{% code title=".gitbook.yaml" %}

```yaml
root: ./docs/
```

{% endcode %}

{% hint style="warning" %}
\\.gitbook.yaml 中的路径 `.gitbook.yaml` 均相对于 `root`。例如，设置 `root: ./docs/`, `structure.summary: ./product/SUMMARY.md` 会解析为 `./docs/product/SUMMARY.md`.
{% endhint %}

在单体仓库中， `root` 仅适用于映射空间目录内的内容，不会使同级目录可用。有关多空间仓库设置，请参阅 [单体仓库](https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync/monorepos.md).

#### 设置首页和导航文件

使用 `structure.readme` 和 `structure.summary` 设置自定义文件路径：

{% code title=".gitbook.yaml" %}

```yaml
structure:
  readme: ./product/README.md
  summary: ./product/SUMMARY.md
```

{% endcode %}

{% hint style="warning" %}
启用 Git Sync 后，请在仓库中管理 `README.md` 文件。在 GitBook 中编辑这些文件可能会造成冲突或生成重复页面。
{% endhint %}

#### 配置重定向

在 `.gitbook.yaml`中配置空间级重定向。重定向路径仅适用于该空间。

你也可以在 GitBook 应用中管理站点级重定向。请参阅 [站点重定向](https://gitbook.com/docs/documentation/zh/publish/site-redirects.md).

### 使用 SUMMARY.md 配置导航

`SUMMARY.md` 用于定义空间的目录。GitBook 会在已配置的 `root` 目录中查找该文件。

如果 GitBook 找不到 `SUMMARY.md`，它会根据你的文件夹和 Markdown 文件推断导航结构。当你在 GitBook 中更改导航时，GitBook 会创建或更新 `SUMMARY.md` 。

为页面组使用二级标题，并为子页面使用嵌套链接。每个页面组标题之后的顶级链接都属于该组，直到下一个页面组标题。水平分隔线不会关闭一个组，因此请将未分组的顶级页面放在第一个组之前：

{% code title="（目录）。可选地还有一个" %}

```markdown
# 目录

## 产品

* [概览](README.md)
  * [开始使用](getting-started.md)
  * [配置](configuration.md)

## 参考

* [API 参考](api.md)
```

{% endcode %}

每个 Markdown 文件在 `SUMMARY.md`中只能出现一次。一个页面在同一空间中只能有一个 URL。

#### 设置导航标签

当导航标签与页面标题不同时，请添加页面链接标题：

{% code title="（目录）。可选地还有一个" %}

```markdown
# 目录

* [页面主标题](page.md "导航标签")
```

{% endcode %}

GitBook 会在侧边栏、分页和相对链接中使用链接标题。它不会更改页面别名或 URL。如果没有链接标题，GitBook 会使用页面标题。

#### 链接到绝对 URL

`SUMMARY.md` 支持使用绝对 URL 进行外部导航和跨空间导航：

{% code title="（目录）。可选地还有一个" %}

```markdown
# 目录

* [GitBook](https://gitbook.com)
* [API 参考](https://app.gitbook.com/s/<spaceId>/api-reference)
```

{% endcode %}

使用 GitBook 绝对 URL 链接到其他空间中的页面。将 `<spaceId>` 替换为目标空间 ID。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync/content-configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
