从 GitBook 迁移到 Docsbook

你遇到了 GitBook 每位编辑的限制。或者 AI 搜索附加组件的价格。或者你注意到你的团队每年支付 $2,400 用于一个索引效果不佳的文档网站。这是实用的迁移指南。

大多数团队在三小时内完成此操作。昂贵的部分是重定向。

简而言之#

将 GitBook 内容导出为 markdown
推送到新的 GitHub 仓库
将 Docsbook 连接到该仓库（5 秒）
在 docsbook.io/yourorg/yourrepo 验证网站
将您的自定义域名 docs.yourcompany.com 连接到 Docsbook (PRO+)
从旧的 GitBook 路径设置重定向
更新您网站上的内部链接

步骤 1：从 GitBook 导出#

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

打开您的 GitBook 空间
设置 → 与 Git 同步 → “将 GitBook 与 Git 提供者同步”
选择 GitHub，选择一个新的私有或公共仓库
GitBook 将您的内容作为带有前置信息的 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 自动从您的文件夹结构和前言 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
网站将在 docsbook.io/yourorg/yourrepo 的 5 秒内上线

如果您的仓库中有 docs/ 文件夹，Docsbook 将使用它。如果您的文档位于根目录，也可以。

步骤 4：自定义域名#

PRO+（$59/月）包括自定义域名。PRO（$150终身）也包括自定义域名。免费版不包括。

在Docsbook仪表板中：

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

步骤 5：重定向#

这是对 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
成本	每编辑器约$200/月	$0 / $150终身 / $59每月
AI聊天	附加组件	内置
AI翻译	不可用	15种语言
MCP服务器	不可用	内置
llms.txt	手动	自动
真实来源	GitBook数据库	您的GitHub仓库

可能会中断的内容#

GitBook特定块 — 可折叠部分、提示块、标签。Docsbook支持标准markdown + Docsbook特定块。大多数GitBook提示可以干净地重写为 > [!NOTE] 提示。
自定义OpenAPI集成 — GitBook有其API参考渲染器。Docsbook通过您现有的工具或链接渲染OpenAPI。
GitBook AI聊天记录 — 不会转移。聊天将从您的新内容开始。

时间#

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

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

昂贵的部分是内部宣传 URL 更改以及更新您支持工具中的保存回复。

开始迁移：将您的 GitHub 仓库粘贴到 docsbook.io。网站在 5 秒内上线，自定义域名在 5 分钟内完成。

Updated Jul 24, 2026