从 GitBook 迁移到 Docsbook：分步指南

当 GitBook 的按用户收费增长速度超过文档本身的增长速度时，你就会意识到问题所在。或者是 AI 附加功能的价格太高。又或者你发现，自己每年都在为一个索引效果不佳的文档网站支付费用。这是一份实用的迁移指南。

大多数团队可以在三小时内完成迁移。最费钱的部分是重定向。

简而言之#

1. 将 GitBook 内容导出为 Markdown
2. 推送到新的 GitHub 仓库
3. 将 Docsbook 连接到该仓库（5 秒）
4. 在 docsbook.io/yourorg/yourrepo 验证网站
5. 将自定义域名 docs.yourcompany.com 连接到 Docsbook
6. 设置从旧 GitBook 路径的重定向
7. 更新整个网站中的内部链接

第 1 步：从 GitBook 导出#

GitBook 支持通过工作区设置导出 Markdown：

• 打开您的 GitBook 空间
• 设置 → 与 Git 同步 →“将 GitBook 与 Git 提供商同步”
• 选择 GitHub，然后选择一个新的私有或公共仓库
• GitBook 会将您的内容以带有 frontmatter 的 Markdown 格式同步

替代方式（不使用 Git 同步）：从空间菜单中选择“导出为 Markdown”选项，然后在本地解压结果。

GitBook 导出的文件夹结构：

README.md
SUMMARY.md
docs/
  introduction.md
  guides/
    quick-start.md
  api/
    auth.md

第 2 步：调整以符合 Docsbook 约定#

需要处理两个小差异：

SUMMARY.md 在 Docsbook 中是可选的#

GitBook 使用 SUMMARY.md 作为导航源。Docsbook 会根据您的文件夹结构和 frontmatter title 自动构建导航。

您可以保留 SUMMARY.md（Docsbook 会忽略它），也可以将其删除。大多数团队都会删除它。

前置元数据#

GitBook 前置元数据：

---
description: How to authenticate
---

Docsbook 读取相同的 description 字段，以及可选的 title。如果缺少 title，则使用第一个 H1。

一个简单的迁移脚本：

find . -name "*.md" -not -path "./.git/*" -exec \
  sed -i.bak '1,/^---$/ s/^description:/description:/' {} \;

（大多数情况下无需更改 — GitBook 和 Docsbook 的前置元数据兼容。）

第 3 步：连接 Docsbook#

• 访问 docsbook.io
• 使用 GitHub 登录
• 粘贴 github.com/yourorg/yourrepo
• 网站将在 5 秒内于 docsbook.io/yourorg/yourrepo 上线

如果您的仓库中有 docs/ 文件夹，Docsbook 会使用它。如果您的文档位于根目录下，也同样有效。

第 4 步：自定义域名#

Docsbook 为 docs.yourcompany.com 提供自动 SSL。

在 Docsbook 控制面板中：

• 设置 → 域名
• 输入 docs.yourcompany.com
• 更新您的 DNS：CNAME docs → cname.vercel-dns.com
• SSL 自动配置且免费

第五步：重定向#

这是唯一一个对 SEO 很重要的步骤。GitBook URL 如下所示：

docs.yourcompany.com/v/1.0/api/authentication

Docsbook URL：

docs.yourcompany.com/api/authentication

你有两个选择：

选项 A：在 DNS/CDN 层级重定向#

如果您的域名前面使用了 Cloudflare，请添加页面规则：

docs.yourcompany.com/v/*/api/* → docs.yourcompany.com/api/$2 [301]

选项 B：通过 Docsbook 重定向#

在仓库根目录添加一个 _redirects 文件（如果你的技术栈支持）：

/v/1.0/api/auth /api/auth 301
/v/1.0/api/webhooks /api/webhooks 301

301 重定向会保留 SEO 权重，而 302 不会——请使用 301。

第 6 步：更新内部引用#

在代码库中搜索并替换：

grep -rl "docs.yourcompany.com/v/" . | xargs sed -i.bak 's|docs.yourcompany.com/v/[0-9.]*/|docs.yourcompany.com/|g'

更新：

• 产品应用页脚链接
• 营销网站
• GitHub 上 README 中的链接
• 支持团队的预设回复

第 7 步：验证 AI 界面#

Docsbook 会自动生成 llms.txt、llms-full.txt、JSON-LD 和站点地图。请检查：

curl https://docs.yourcompany.com/llms.txt | head -20
curl https://docs.yourcompany.com/sitemap.xml | head -10

有关预期内容，请参阅 llms.txt：完整指南。

有哪些改进#

可能出现问题的地方#

• GitBook 特有的区块 — 可折叠部分、提示区块、标签页。Docsbook 支持标准 Markdown 以及 Docsbook 特有的区块。大多数 GitBook 提示都可以顺利改写为 > [!NOTE] 调用框。
• 自定义 OpenAPI 集成 — GitBook 具有自己的 API 参考渲染器。Docsbook 通过现有工具渲染 OpenAPI，或链接到外部页面。
• GitBook AI 聊天记录 — 不会迁移。聊天会随着新内容的加入而重新开始。

时间#

根据我们帮助团队迁移的经验：

• 个人创始人，约 50 个页面：1 小时
• 小型初创公司，约 200 个页面：3 小时
• 中期公司，约 1000 个页面，自定义域名：半天

耗时较多的部分，是在内部推广 URL 变更，以及更新支持工具中的预设回复。

免费开始 — 无需信用卡

下一步#

• GitBook 与 Docsbook — 此次迁移背后的功能逐项对比
• 为文档设置自定义域名 — 第 4 步中的 DNS 和 SSL 部分
• 文档 SEO 指南 — 如何在 URL 更改期间保持排名