内容配置

为 Git 同步配置额外功能

如果你想进一步配置 Git Sync，你可以添加一个 .gitbook.yaml 文件到你仓库的根目录，以告诉 GitBook 如何解析你的 Git 仓库。

.gitbook.yaml

root: ./

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

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

根目录

用于查找文档的路径默认是仓库的根目录。以下是告诉 GitBook 去查看 ./docs 文件夹的方法：

.gitbook.yaml

root: ./docs/

所有其他指定路径的选项都将相对于此根文件夹。因此，如果你将 root 定义为 ./docs/ ，然后将 structure.summary 设置为 ./product/SUMMARY.md，GitBook 实际上会在 ./docs/product/SUMMARY.md查找文件。

Structure

structure 接受两个属性：

• readme: 你的文档首页。其默认值为 ./README.md

• summary: 你的文档目录（Table of Contents）。其默认值为 ./SUMMARY.md

这些属性的值是对应文件的路径。该路径相对于“root”选项。例如，以下是告诉 GitBook 去查看 ./product 文件夹中的首页和目录的方法：

.gitbook.yaml

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

启用 Git Sync 时， 请记住不要创建或修改 readme 文件 通过 GitBook 的界面进行操作。为避免冲突和重复，readme 文件应仅在你的 GitHub/GitLab 仓库中进行管理。

Summary

该 summary 文件是一个 Markdown 文件（.md），应具有以下结构：

./SUMMARY.md

# Summary

## 使用标题创建类似这样的页面分组

* [首页标题](page1/README.md)
    * [某个子页面](page1/page1-1.md)
    * [另一个子页面](part1/page1-2.md)

* [第二页的标题](page2/README.md)
    * [某个子页面](page2/page2-1.md)
    * [另一个子页面](part2/page2-2.md)

## 第二个页面分组

* [另一个页面](another-page.md)

提供自定义的 summary 文件是可选的。默认情况下，GitBook 会查找名为 SUMMARY.md 的文件，位于你的 root 文件夹（如果在配置文件中指定），否则位于仓库根目录。

如果你未指定 summary，且 GitBook 也没有在文档根目录找到 SUMMARY.md 文件，GitBook 将根据文件夹结构和下面的 Markdown 文件来推断目录。

summary Markdown 文件是 你 GitBook 空间 目录（Table of Contents） 的镜像。因此，即使在初始导入时未提供 summary 文件，GitBook 也会在你使用 GitBook 编辑器更新内容时创建并/或更新它。

因此，在你的 SUMMARY.md 文件中无法两次引用同一个 Markdown 文件，因为这意味着同一页面在你的 GitBook 空间中会对应两个不同的 URL。

Redirects

重定向允许你在 .gitbook.yaml 配置文件中定义重定向。路径相对于“root”选项。例如，以下是告诉 GitBook 将访问旧网址的用户 /help 重定向到新网址 /support

.gitbook.yaml

root: ./

redirects:
  help: support.md

你在空间配置文件中定义的重定向只作用于对应的空间。我们建议在大多数情况下创建 站点重定向 ，因为它们适用于整个站点，跨越多个空间。

在 Git 中，当一个文件被多次移动时，原文件会被删除并创建一个新文件。例如，这使得 GitBook 无法知道某个文件夹已被重命名。请务必仔细检查并在需要的地方添加重定向。