> 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/monorepos.md).

# 单仓库

在单仓库中使用 Git Sync，并将空间映射到独立目录

使用站点级 Git Sync，可从一个仓库和分支同步多个空间。将每个空间映射到 `gitbook-docs.yaml`.

### 站点级 Git Sync 的工作方式

站点的 **项目目录** 用于设置 Git Sync 的安装目录。 `gitbook-docs.yaml` 文件位于该目录中。如果留空，GitBook 将使用仓库根目录。

在 `gitbook-docs.yaml`中，每个空间都有一个 `content.directory`。该目录包含空间的 `.gitbook.yaml`, `README.md`, `SUMMARY.md`和内容文件。

如需了解这些文件的概述，请参阅 [内容配置](https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync/content-configuration.md).

### 将空间映射到目录

在 Git Sync 面板中使用 **内容映射** 来映射每个空间。GitBook 会将映射保存到 `gitbook-docs.yaml`.

目录路径的规则如下：

| 路径       | 含义           |
| -------- | ------------ |
| `./docs` | 项目目录中的一个目录。  |
| `/docs`  | 仓库根目录中的一个目录。 |
| `docs`   | 与 `./docs`.  |

例如，此仓库将三个空间映射到不同目录：

```
/
  gitbook-docs.yaml
  documentation/
    .gitbook.yaml
    （主页）和
    （目录）。可选地还有一个
    .gitbook/
      assets/
        logo.png
  developers/
    .gitbook.yaml
    （主页）和
    （目录）。可选地还有一个
  changelog/
    .gitbook.yaml
    （主页）和
    （目录）。可选地还有一个
```

此 `gitbook-docs.yaml` 文件将每个空间映射到相应目录：

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

```yaml
$schema: https://api.gitbook.com/gitbook-docs.yaml
site:
  structure:
    - type: space
      key: documentation
      title: 文档
      path: documentation
      content:
        directory: ./documentation
    - type: space
      key: developers
      title: Developers
      path: developers
      content:
        directory: ./developers
    - type: space
      key: changelog
      title: Changelog
      path: changelog
      content:
        目录：./changelog
```

{% endcode %}

### 确保空间内容自成一体

每个空间只会同步分配给它的目录。GitBook 不会在映射的目录之间自动共享内容或资源。

确保每个引用的资源都位于其所属空间映射的目录中。如果多个空间需要同一资源，请将副本添加到各自的目录中，或重新整理仓库结构。

“ `.gitbook.yaml` `root` ”设置用于控制 GitBook 在该空间映射的目录中读取内容的位置。它不会让同级目录也变为可用。

### 移动映射的目录

要移动某个空间的内容，请同时更新其文件和映射：

1. 在仓库中移动该空间的内容文件和资源。
2. 在 `gitbook-docs.yaml`中，更新该空间的 `content.directory`。保留其 `key` 不变。
3. 在同一次提交中提交这两项更改。

{% hint style="info" %}
如果 GitBook 在两项更改都完成之前导入内容，映射的空间可能会显示为空。
{% endhint %}

{% hint style="danger" %}
**不要将 `key` 重命名为与新目录相同的名称。** 键与目录名称彼此独立。更改空间的键会用一个新的空间替换原空间，并生成新的空间 ID；即使恢复原来的键，也无法找回旧 ID。请参阅 [键用于标识空间](https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync/content-configuration.md#keys-identify-your-spaces).
{% endhint %}

由 GitBook 生成的键—— `space-1`, `space-2` ——与目录名称无关，因此无需让两者保持一致。

### 使用单个空间的 Git 同步

如果某个空间需要使用其他仓库或分支，请使用单个空间的 Git 同步。例如，私有空间需要单独同步时，就可以使用此方式。

先从站点的内容映射中移除该空间，然后在该空间中配置 Git 同步。

要配置该空间，请按照 [启用 GitHub 同步](https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync/enabling-github-sync.md) 或 [启用 GitLab 同步](https://gitbook.com/docs/documentation/zh/docs-as-code/git-sync/enabling-gitlab-sync.md)进行操作。在范围步骤中，选择 **空间 Git 同步**.


---

# 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/monorepos.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.
