单体仓库

GitBook 支持 monorepo。Monorepo 是指包含多个逻辑项目的仓库（例如，一个 iOS 客户端和一个 Web 应用程序）。

GitBook 可以将同一仓库中的多个目录与多个空间同步。为某个空间启用 Git Sync 时，你可以配置一个“项目目录”。它将用于查找 .gitbook.yaml 该目录中用于与此空间同步的文件。

仓库结构示例：

/
  package.json
  packages/
     styleguide/
        .gitbook.yaml
        README.md
        SUMMARY.md
     app/
        README.md
        SUMMARY.md
     api/
        .gitbook.yaml
        README.md
        SUMMARY.md

在此示例中，可以在 GitBook 上创建三个空间，并为它们配置不同的项目目录：

• packages/styleguide

• packages/app

• packages/api

Git Sync 级别的“项目目录”选项不同于 根 选项 在 .gitbook.yaml 配置文件中。前者用于查找 .gitbook.yaml 它本身，然后两者结合起来查找该目录中的其余文件。如果没有 .gitbook.yaml 存在于“项目目录”中，同步将使用作用域限定为该目录的默认配置。

多空间仓库中目录和资源的工作方式

每个同步的空间都有其自己的 项目目录。GitBook 会读取该空间的 .gitbook.yaml 来自已配置的项目目录。然后它会解析 根, README.md, SUMMARY.md、Markdown 文件以及该空间同步范围内的资源路径。

在 monorepo 中，每个同步的空间都限定在自己的目录和文件范围内。从其他目录同步的不同空间不会自动继承或复用仓库中其他位置的文件。

资源遵循相同规则。仓库级别的 .gitbook/assets 文件夹不会在各空间之间自动共享，前提是这些空间使用不同的项目目录。

如果多个空间需要相同的文件，请使用以下模式之一：

• 将资源放在每个空间各自的目录中。

• 重新组织仓库，使每个空间的同步范围都包含其引用的资源。

在 monorepo 中设置新空间时，请先在仓库中创建你想要的目录结构。GitBook 不会替你推断共享的多空间布局，也不会为你创建共享的资源区域。

有关如何 根 在空间同步范围内被解析，请参阅 内容配置.

下面是一个具体示例：

/
  packages/
    docs-en/
      .gitbook.yaml
      README.md
      SUMMARY.md
      .gitbook/
        assets/
          logo.png
    docs-fr/
      .gitbook.yaml
      README.md
      SUMMARY.md
      .gitbook/
        assets/
          logo.png

在此仓库中， packages/docs-en 和 packages/docs-fr 是两个独立的同步空间。引用自 packages/docs-en/.gitbook/assets/logo.png 不会自动对从以下位置同步的空间可用： packages/docs-fr.

更新项目目录

在大多数情况下，我们建议按以下步骤更新项目目录：

1. 禁用现有的 Git Sync

2. 将 Git 仓库中的文件移动到项目目录

3. 使用新的项目目录重新配置 Git Sync

在某些情况下，你可能最初使用的是一个仅与一个空间同步的普通仓库，但后来决定将其过渡为一个与多个空间同步的 monorepo；或者可能需要重命名项目目录。

更改现有 Git Sync 的项目目录可能会对内容产生意外影响，该更改只会在下一次同步时传播（在 GitBook 中所做的编辑或 Git 仓库中的新提交）。

GitBook 期望该空间所有与 GitBook 相关的文件都存在于已配置的项目目录中。这包括 Markdown 文件， README.md, SUMMARY.md以及该空间使用的任何资源。

如果下一步操作是从 Git 仓库导入:

GitBook 会期望在项目目录中找到页面和文件。如果这些文件尚未被移动到仓库的项目目录中，同步的结果将是一个没有内容的空空间。

我们建议下一步操作是通过一次提交，将仓库中所有与 GitBook 相关的文件（markdown 文件、README/SUMMARY 和资源）移动到项目目录中的正确新位置。如果资源仍然位于新的项目目录之外，不要指望它们能在该空间中被解析。

如果下一步操作是从 GitBook 导出到 Git 仓库:

GitBook 将在新的项目目录中生成或更新新文件。与 GitBook 同步的文件将被尽力移动到新的项目目录；如果系统的其他部分依赖这些文件，可能会产生副作用。