选择一种方式
在可能的情况下，将 Git Sync 用作主要迁移方式。一个 GitBook 站点由多个 section 组成，每个 section 可以有多个 variant，而 Git Sync 在 section 级别上运行。请导出出现在已发布站点上的每个 section。
GitBook 现在将站点内的内容容器称为 section。较旧的 GitBook 文档和社区脚本称其为 space。
使用 Git Sync 导出 section
- 创建一个空的 GitHub 或 GitLab 仓库，或者在迁移仓库中创建一个空分支。
- 在你要导出的 section 中，点击 section 标题旁 Git Sync 下方的 Set up。
- 从提供商列表中，点击 GitHub Sync 或 GitLab Sync，如果尚未连接提供商，请先进行身份验证。
- 选择空仓库和用于导出的分支。
- 对于初始同步方向，选择 GitBook → GitHub 或 GitBook → GitLab。
- 开始初始同步。完成后，克隆或下载该仓库。
- 对需要迁移的每个 section、语言或版本重复上述步骤。
迁移公开站点
-p puppeteer 参数会安装 Puppeteer，抓取工具使用它在浏览器中渲染站点。如果未安装 Puppeteer，抓取工具会在不使用浏览器的情况下获取页面，生成的导航可能不完整。
抓取工具会加载 GitBook 已渲染的导航、下载可到达的图片、转换常见的 block，并创建 docs.json。它无法检索私有 section、未发布的更改、权限、评论或修订历史。
在两者都可用时，将生成的项目与 Git Sync 导出进行比较。抓取对于检查渲染 block 的转换很有用，而导出则是源内容更完整的清单。
理解 Git Sync 导出
README.md：Section 主页SUMMARY.md：目录.gitbook.yaml：内容根、结构和 section 重定向.gitbook/assets/：上传的图片和文件.gitbook/includes/：可复用内容
SUMMARY.md 是一个嵌套的 Markdown 列表。将其标题和链接转换为 docs.json 导航：
从导航路径中移除
.md 扩展名，但不要在检查链接之前重命名所有文件。像 guides/README.md 这样的页面可以变成 guides/index.mdx，也可以保留为具有不同导航路径的 Markdown 文件。
每个 Mintlify 页面也需要至少包含 title 的 frontmatter。在迁移每个页面时，添加或转换 frontmatter。
社区脚本可以自动完成
SUMMARY.md 的递归映射。在运行之前，请检查它们生成的文件移动和 shell 命令。转换器必须能处理缺失链接、外部 URL、重复页面、嵌套分组和 GitBook 内容根，且不能覆盖源文件。转换 GitBook block
{% ... %} 指令来表示 block。将这些指令转换为 Mintlify 组件。
GitBook 将一些自定义 block 导出为 HTML，因为它们没有 Markdown 表示。请检查每个 HTML block，确认它在 MDX 中的表现一致。
转换可复用内容
.gitbook/includes/ 目录，并通过 include 指令引用它们。将每个可复用文件转换为 Mintlify snippet，然后将 GitBook 的 include 替换为 MDX 导入和组件。
例如：
迁移 section、variant 和翻译
- 将产品或受众 section 映射到 products、tabs 或 anchors。
- 将发布 variant 映射到 versions。
- 将翻译的 section 映射到 languages。
- 当用户不需要选择器时，将独立的内容集合映射到独立分组。
迁移资源和链接
.gitbook/assets/ 复制到你的 Mintlify 仓库中，并在移动页面后更新相对图片和下载路径。检查使用 HTML 设置尺寸或对齐方式的内联图片。除非你在迁移后打算继续保留 GitBook 托管，否则不要将必需的生产资源留在 GitBook 上。
GitBook 的重定向可以存在于配置文件和站点级设置中。收集这两个来源并将其转换为 Mintlify 的 重定向。GitBook 会将其配置文件中的重定向限定在单个 section 内，而 Mintlify 的重定向适用于整个已发布站点。必要时请包含以前的 section 或 variant 前缀。
迁移 OpenAPI 文档
- 清点你的 GitBook 组织中的所有 OpenAPI 规范。
- 通过 GitBook API 获取原始文件、托管源 URL 或规范。
- 将 JSON 或 YAML 文件添加到你的 Mintlify 仓库。
- 配置 OpenAPI 生成的页面。
- 用普通 GitBook block 中的说明重建相邻的解释性内容。
- 将认证、服务器 URL、示例和 GitBook 特有的 OpenAPI 扩展与你的 Mintlify API 页面进行比较。
检查你的迁移
SUMMARY.md 条目与 docs.json 进行比较，然后验证每个 section、group、variant 和语言。
在你转换后的文件中搜索遗留的 GitBook 语法：{%、{% end、.gitbook/includes，以及 GitBook 用来替代 Markdown 导出的原始 HTML block。
启动你的新站点
- 在旧站点上执行内容冻结，并跟踪迁移快照之后对其所做的每项更改。
- 在仪表板的 Git 设置 页面确认生产分支和仓库。
- 记录你现有的 DNS 记录，并在验证 Mintlify 站点已上线之前保持旧站点继续运行。
- 检查导航栏、页脚、favicon、logo、颜色和字体。
- 检查站点和页面的元数据、canonical URL 以及索引偏好设置。参见 SEO 和搜索设置。
- 安装所需的 分析集成，并可选择添加一个 自定义 404 页面。
- 如果你迁移了 API 参考，请将端点页面、导航结构、服务器 URL、认证方案和示例与旧站点进行比较。
- 在 预览部署 中预览你确切的启动提交。检查桌面和移动端布局、来自每个导航区段的页面、搜索以及重定向。
- 检查使用自定义组件或脚本的页面在浏览器控制台和网络标签页中是否有任何错误。
- 使用 自定义域名指南 切换你的域名，该指南涵盖了对已提供文档服务的域名的零停机切换。
- 启动后，监控 404 错误、重定向失败和构建失败。