GitBook Agent is here! Introducing a new way to ideate, plan, and ship docs.
Find out more
PricingLog inSign up

内容配置

配置 Git 同步并启用额外功能

如果您想进一步配置 Git 同步，您可以添加一个 .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。.‌

​结构‌

该结构接受两个属性：‌

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

  • summary: 您文档的目录。其默认值为 ./SUMMARY.md

这些属性的值是对应文件的路径。路径相对于“root”选项。例如，下面是如何告诉 GitBook 在一个 ./product 文件夹中查找首页和目录：

当启用 Git 同步时， 请记住不要通过 GitBook 的界面创建或修改 readme 文件 readme 文件应当专门在您的 GitHub/GitLab 仓库中进行管理，以避免冲突和重复问题。

目录（Summary）‌

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

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

如果您未指定 summary，且 GitBook 在您的文档根目录未找到 SUMMARY.md 文件，GitBook 将从文件夹结构和下面的 Markdown 文件推断目录（表）。‌

summary Markdown 文件是 您的 GitBook 空间的目录（目录结构）的镜像。 因此即使在初始导入期间未提供 summary 文件，GitBook 也会在您使用 GitBook 编辑器更新内容时创建和/或更新该文件。

因此，在您的 SUMMARY.md 文件中不可能多次引用同一个 Markdown 文件，因为这意味着同一页面会出现在 GitBook 空间的两个不同 URL 下。

目录（侧边栏）标题

如果您希望页面在目录侧边栏中的标题与页面本身不同，您可以定义一个可选的 页面链接标题 的文件，位于您的 SUMMARY.md 文件。

如果您使用 Git 同步，页面链接标题在页面链接上设置：

引号内的文本（"页面链接标题"）将被用于：

  • 在目录（侧边栏）中

  • 在每页底部的分页按钮中

  • 在您为该页面添加的任何相对链接中

页面链接标题是可选的——如果您不手动添加，GitBook 将默认在所有地方使用页面的标准标题。

​重定向

重定向允许您在您的 .gitbook.yaml 配置文件中定义重定向。路径相对于“root”选项。例如，下面是如何告诉 GitBook 将访问过去 URL 的用户重定向到一个新的 URL： /help 到新的 URL /support

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

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

最后更新于

这有帮助吗？