> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 从 GitBook 迁移

> 将 GitBook 的 sections、Markdown、导航、可复用内容、variants、资源和 OpenAPI 文档迁移到 Mintlify。

使用 Git Sync 将 GitBook 内容导出到 Git 仓库以获得最完整的迁移，或抓取公开的 GitBook 站点来创建初始的 Mintlify 项目。

<div id="choose-a-method">
  ## 选择一种方式
</div>

| 方式          | 适用场景                                                |
| ----------- | --------------------------------------------------- |
| Git Sync 导出 | 你是 GitBook 站点的管理员，或需要源 Markdown、可复用内容、私有页面或稳定的迁移快照。 |
| 自动抓取工具      | 你的 GitBook 站点是公开的，并希望快速转换已渲染的页面、常见 block、资源和导航。     |

在可能的情况下，将 Git Sync 用作主要迁移方式。一个 GitBook 站点由多个 section 组成，每个 section 可以有多个 variant，而 Git Sync 在 section 级别上运行。请导出出现在已发布站点上的每个 section。

<Note>
  GitBook 现在将站点内的内容容器称为 section。较旧的 GitBook 文档和社区脚本称其为 space。
</Note>

<div id="export-a-section-with-git-sync">
  ## 使用 Git Sync 导出 section
</div>

GitBook 不为单个页面提供直接的 Markdown 下载。要将 section 导出为 Markdown：

1. 创建一个空的 GitHub 或 GitLab 仓库，或者在迁移仓库中创建一个空分支。
2. 在你要导出的 section 中，点击 section 标题旁 **Git Sync** 下方的 **Set up**。
3. 从提供商列表中，点击 **GitHub Sync** 或 **GitLab Sync**，如果尚未连接提供商，请先进行身份验证。
4. 选择空仓库和用于导出的分支。
5. 对于初始同步方向，选择 **GitBook → GitHub** 或 **GitBook → GitLab**。
6. 开始初始同步。完成后，克隆或下载该仓库。
7. 对需要迁移的每个 section、语言或版本重复上述步骤。

<Warning>
  初始同步方向很重要。选择 **GitHub → GitBook** 或 **GitLab → GitBook** 会用所选分支的内容替换你的 section 内容，而不是导出 section。请确认方向从 GitBook 出发，指向你的空仓库。如果你选错了方向，请在该 section 的版本历史中回滚到 Git Sync 操作之前的修订版本。
</Warning>

保持已同步的仓库不变，作为迁移快照。为你的 Mintlify 转换创建一个分支或副本。

<div id="migrate-a-public-site">
  ## 迁移公开站点
</div>

<Warning>
  抓取工具会覆盖目录中已有的文件。

  请在空目录中运行抓取工具。
</Warning>

```bash theme={null}
mkdir mintlify-migration
cd mintlify-migration
npx @mintlify/scraping@latest section https://docs.example.com
```

抓取工具会加载 GitBook 已渲染的导航、下载可到达的图片、转换常见的 block，并创建 `docs.json`。它无法检索私有 section、未发布的更改、权限、评论或修订历史。

在两者都可用时，将生成的项目与 Git Sync 导出进行比较。抓取对于检查渲染 block 的转换很有用，而导出则是源内容更完整的清单。

<div id="understand-the-git-sync-export">
  ## 理解 Git Sync 导出
</div>

GitBook 通常创建或使用以下文件和目录：

* `README.md`：Section 主页
* `SUMMARY.md`：目录
* `.gitbook.yaml`：内容根、结构和 section 重定向
* `.gitbook/assets/`：上传的图片和文件
* `.gitbook/includes/`：可复用内容

当 GitBook 配置定义了其他内容根、主页或摘要文件时，路径可能有所不同。在移动任何文件之前，请确认你的具体配置。

<div id="convert-summarymd-navigation">
  ## 转换 `SUMMARY.md` 导航
</div>

`SUMMARY.md` 是一个嵌套的 Markdown 列表。将其标题和链接转换为 `docs.json` 导航：

| GitBook `SUMMARY.md` | Mintlify                    |
| -------------------- | --------------------------- |
| 标题                   | 导航分组或其他分区                   |
| 顶级链接项                | 页面路径                        |
| 带子项的链接项              | 带 `root` 和嵌套 `pages` 的分组    |
| 嵌套链接项                | 页面或嵌套分组                     |
| `README.md`          | Section 或分组的概览页面            |
| 外部链接                 | 在支持的位置使用导航链接，或使用指向外部资源的普通页面 |

从导航路径中移除 `.md` 扩展名，但不要在检查链接之前重命名所有文件。像 `guides/README.md` 这样的页面可以变成 `guides/index.mdx`，也可以保留为具有不同导航路径的 Markdown 文件。

每个 Mintlify 页面也需要至少包含 `title` 的 frontmatter。在迁移每个页面时，添加或转换 frontmatter。

<Note>
  社区脚本可以自动完成 `SUMMARY.md` 的递归映射。在运行之前，请检查它们生成的文件移动和 shell 命令。转换器必须能处理缺失链接、外部 URL、重复页面、嵌套分组和 GitBook 内容根，且不能覆盖源文件。
</Note>

<div id="convert-gitbook-blocks">
  ## 转换 GitBook block
</div>

GitBook 使用许多 `{% ... %}` 指令来表示 block。将这些指令转换为 Mintlify 组件。

| GitBook 源                              | Mintlify 替代方案                                                                    |
| -------------------------------------- | -------------------------------------------------------------------------------- |
| `{% hint style="info" %}`              | [`Info`](/docs/zh/components/callouts)                                                |
| `hint` 样式 `success`                    | [`Check`](/docs/zh/components/callouts) 或 `Tip`                                       |
| `hint` 样式 `warning`                    | [`Warning`](/docs/zh/components/callouts)                                             |
| `hint` 样式 `danger`                     | [`Danger`](/docs/zh/components/callouts)                                              |
| `{% tabs %}` 和 `{% tab title="..." %}` | [`Tabs` 和 `Tab`](/docs/zh/components/tabs)                                            |
| 可展开 block                              | [`Accordion`](/docs/zh/components/accordions)                                         |
| 代码 tab                                 | [`CodeGroup`](/docs/zh/components/code-groups)                                        |
| Cards 和 columns                        | [`Card`、`CardGroup`](/docs/zh/components/cards) 或 [`Columns`](/docs/zh/components/columns) |
| 嵌入的媒体或集成 block                         | 受支持的 [嵌入](/docs/zh/create/image-embeds)、链接、图片或自定义 React 组件                            |

GitBook 将一些自定义 block 导出为 HTML，因为它们没有 Markdown 表示。请检查每个 HTML block，确认它在 MDX 中的表现一致。

<div id="convert-reusable-content">
  ## 转换可复用内容
</div>

GitBook 将可复用内容导出到 `.gitbook/includes/` 目录，并通过 include 指令引用它们。将每个可复用文件转换为 [Mintlify snippet](/docs/zh/create/reusable-snippets)，然后将 GitBook 的 include 替换为 MDX 导入和组件。

例如：

```mdx theme={null}
import Authentication from "/snippets/authentication.mdx";

<Authentication />
```

检查跨多个 section 共享的可复用内容。GitBook 会指定一个拥有该内容的父 section，且这是它可被编辑的唯一位置，因此单独的 section 导出可能包含需要合并为单一共享 snippet 的重复内容或跨 section 引用。

<div id="migrate-sections-variants-and-translations">
  ## 迁移 section、variant 和翻译
</div>

GitBook 站点会发布一个或多个 section，将相关的 section 组织成 group，并使用 variant 表示版本或语言。选择最接近的 Mintlify 导航模型：

* 将产品或受众 section 映射到 [products](/docs/zh/organize/navigation#products)、tabs 或 anchors。
* 将发布 variant 映射到 [versions](/docs/zh/organize/navigation#versions)。
* 将翻译的 section 映射到 [languages](/docs/zh/organize/navigation#languages)。
* 当用户不需要选择器时，将独立的内容集合映射到独立分组。

在更改域名之前，记录默认 variant 和每个 variant 的 slug。GitBook 可以从其公共 URL 中省略默认 variant 的 slug，因此重定向必须同时考虑默认路径和显式命名的路径。

<div id="migrate-assets-and-links">
  ## 迁移资源和链接
</div>

将 `.gitbook/assets/` 复制到你的 Mintlify 仓库中，并在移动页面后更新相对图片和下载路径。检查使用 HTML 设置尺寸或对齐方式的内联图片。除非你在迁移后打算继续保留 GitBook 托管，否则不要将必需的生产资源留在 GitBook 上。

GitBook 的重定向可以存在于配置文件和站点级设置中。收集这两个来源并将其转换为 Mintlify 的 [重定向](/docs/zh/create/redirects)。GitBook 会将其配置文件中的重定向限定在单个 section 内，而 Mintlify 的重定向适用于整个已发布站点，因此必要时请包含以前的 section 或 variant 前缀。

<div id="migrate-openapi-documentation">
  ## 迁移 OpenAPI 文档
</div>

GitBook 可以在组织级别存储 OpenAPI 规范，并在 section 中放置生成的 OpenAPI block。Markdown section 导出可能不是这些规范的真实来源。

1. 清点你的 GitBook 组织中的所有 OpenAPI 规范。
2. 通过 GitBook API 获取原始文件、托管源 URL 或规范。
3. 将 JSON 或 YAML 文件添加到你的 Mintlify 仓库。
4. 配置 [OpenAPI 生成的页面](/docs/zh/api-playground/openapi-setup)。
5. 用普通 GitBook block 中的说明重建相邻的解释性内容。
6. 将认证、服务器 URL、示例和 GitBook 特有的 OpenAPI 扩展与你的 Mintlify API 页面进行比较。

<div id="review-your-migration">
  ## 检查你的迁移
</div>

将每个导出的 section 和 `SUMMARY.md` 条目与 `docs.json` 进行比较，然后验证每个 section、group、variant 和语言。

在你转换后的文件中搜索遗留的 GitBook 语法：`{%`、`{% end`、`.gitbook/includes`，以及 GitBook 用来替代 Markdown 导出的原始 HTML block。

## 启动你的新站点

* 在旧站点上执行内容冻结，并跟踪迁移快照之后对其所做的每项更改。
* 在仪表板的 [Git 设置](https://app.mintlify.com/settings/deployment/git-settings) 页面确认生产分支和仓库。
* 记录你现有的 DNS 记录，并在验证 Mintlify 部署已上线之前保持旧站点继续运行。
* 检查导航栏、页脚、favicon、logo、颜色和字体。
* 检查站点和页面的元数据、canonical URL 以及索引偏好设置。参见 [SEO 和搜索设置](/docs/zh/organize/settings-seo)。
* 安装所需的 [分析集成](/docs/zh/integrations/analytics/overview)，并可选择添加一个 [自定义 404 页面](/docs/zh/customize/custom-404-page)。
* 如果你迁移了 API 参考，请将端点页面、导航结构、服务器 URL、认证方案和示例与旧站点进行比较。
* 在 [预览部署](/docs/zh/deploy/preview-deployments) 中预览你确切的启动提交。检查桌面和移动端布局、来自每个导航区段的页面、搜索以及重定向。
* 检查使用自定义组件或脚本的页面在浏览器控制台和网络标签页中是否有任何错误。
* 使用 [自定义域名指南](/docs/zh/customize/custom-domain) 切换你的域名，该指南涵盖了对已提供文档服务的域名的零停机切换。
* 启动后，监控 404 错误、重定向失败和构建失败。

<div id="gitbook-references">
  ## GitBook 参考资料
</div>

* [Git Sync](https://gitbook.com/docs/getting-started/git-sync)
* [启用 GitHub Sync](https://gitbook.com/docs/getting-started/git-sync/enabling-github-sync)
* [内容配置](https://gitbook.com/docs/getting-started/git-sync/content-configuration)
* [内容结构](https://gitbook.com/docs/creating-content/content-structure)
* [可复用内容](https://gitbook.com/docs/creating-content/reusable-content)
* [内容 variants](https://gitbook.com/docs/publishing-documentation/site-structure/variants)
* [OpenAPI](https://gitbook.com/docs/api-references/openapi)
* [添加 OpenAPI 规范](https://gitbook.com/docs/api-references/openapi/add-an-openapi-specification)


## Related topics

- [迁移概览](/docs/zh/migration/index.md)
- [从 Fern 迁移](/docs/zh/migration/fern.md)
- [从 Docusaurus 迁移](/docs/zh/migration/docusaurus.md)