从 Docusaurus 迁移到 Docsbook：分步指南

Docusaurus 在下一次重大迁移到来之前都很出色，而迁移一旦发生，你可能会花费一个冲刺周期处理它，而不是交付产品。本指南将带你了解切实可行的迁移路径。

我们打造了 Docsbook。我们也会告诉你什么时候不值得迁移。

不应迁移的情况#

如果符合以下情况，请跳过此次迁移：

• 您的 Docusaurus 网站大量嵌入 React 组件（交互式演示、自定义插件）。Docsbook 以 Markdown 为核心。
• 您有一名专职文档工程师，其工作有一部分涉及 Docusaurus。该平台在他们手中确实具有优势。
• 您需要高度定制的 React 主题。Docsbook 提供颜色令牌、字体、布局切换以及页眉/页脚配置，但不支持完整的主题魔改。

如果符合上述任一情况，请继续使用 Docusaurus，稍后再阅读本指南的其余部分。

要点速览#

1. 将 MDX 特有语法转换为标准 Markdown
2. 推送到 GitHub 仓库（你已经有一个）
3. 连接 Docsbook
4. 绑定自定义域名
5. 迁移重定向
6. 移除 CI 流水线并停止支付托管费用

步骤 1：将 MDX 转换为 Markdown#

Docusaurus 使用 MDX，即 Markdown + JSX。Docsbook 使用带扩展的标准 Markdown。

需要处理的三类 MDX：

导入和 React 组件#

import Foo from '@site/src/components/Foo';
 
<Foo />

解决方案：

• 对于静态视觉内容：替换为托管图像，并添加指向在线演示的链接
• 对于交互元素：链接到您的应用
• 对于标签页/提示框：使用 Docsbook 的原生区块（见下文）

提示#

Docusaurus：

:::note Title
Content
:::

Docsbook（GitHub 风格的 Markdown）：

> [!NOTE]
> Content

查找和替换：

find . -name "*.mdx" -exec rename 's/\.mdx$/\.md/' {} \;
find . -name "*.md" -exec sed -i.bak -E 's/:::note/> [!NOTE]/g; s/:::tip/> [!TIP]/g; s/:::warning/> [!WARNING]/g; s/:::caution/> [!CAUTION]/g; s/:::info/> [!NOTE]/g; s/^:::$//' {} \;

标签页和代码组#

Docsbook 通过标准语法支持标签页：

<Tabs>
  <Tab title="npm">npm install foo</Tab>
  <Tab title="pnpm">pnpm add foo</Tab>
</Tabs>

大多数 Docusaurus 标签页都可以一一对应地转换。

第 2 步：侧边栏和导航#

Docusaurus 使用 sidebars.js 定义导航。Docsbook 根据文件夹结构和 frontmatter 构建导航。

如果需要指定顺序：

---
title: "Quick Start"
order: 1
---

如果未指定顺序，Docsbook 会按字母顺序排序。如果需要明确分组，请将文件移入已排序的文件夹。

迁移后可以删除 sidebars.js、docusaurus.config.js、babel.config.js 和 src/ 目录。

第 3 步：连接 Docsbook#

您的文档已位于 docs/ 中。连接代码仓库：

• docsbook.io → 使用 GitHub 登录
• 粘贴 github.com/yourorg/yourrepo
• 网站已上线于 docsbook.io/yourorg/yourrepo

步骤 4：自定义域名#

Docsbook 通过自动 SSL 提供 docs.yourcompany.com。

• Docsbook 仪表板 → 设置 → 域名
• 输入 docs.yourcompany.com
• 更新 DNS：CNAME docs → cname.vercel-dns.com
• 等待 5 分钟以启用 SSL

第 5 步：URL 保留#

Docusaurus URL 通常如下所示：

docs.yourcompany.com/docs/intro
docs.yourcompany.com/docs/category/guides/getting-started

Docsbook URL 与文件路径匹配：

docs.yourcompany.com/intro.md → docs.yourcompany.com/intro
docs.yourcompany.com/guides/getting-started.md → docs.yourcompany.com/guides/getting-started

如果您的 Docusaurus 使用了 /docs/ 前缀，并且希望保持一致：

选项 A：重命名本地 docs/ 文件夹，以在 URL 中保留此前缀（Docsbook 将从不同路径提供服务）。

选项 B：在 CDN 或 DNS 层为旧的 /docs/* URL 添加指向新的 /* URL 的重定向。

第 6 步：移除 CI/CD#

Docsbook 开始提供流量后：

# Files you can delete
rm -rf .docusaurus/
rm -rf build/
rm -rf node_modules/
rm docusaurus.config.js
rm sidebars.js
rm babel.config.js
rm -rf src/
rm -rf static/
# Keep docs/ — it is your source

用于部署 Docusaurus 的 GitHub Actions 工作流文件：也删除。

结果是：文档在每次 git push 到 main 时部署，不消耗 CI 分钟数。

您获得的收益#

你放弃的内容#

• 文档中的 React 组件嵌入（将其托管在其他位置，然后链接到这里）
• 完整的 swizzle 主题控制（你将获得颜色、字体和布局令牌）
• 插件生态系统（大多数情况下已内置）

边缘情况#

Algolia DocSearch#

您可以继续在 Docsbook 上使用 Algolia DocSearch（将其指向您的新域名）。或者使用 Docsbook 内置的搜索功能，该功能免费提供。

自定义着陆页#

Docusaurus 通常在 / 使用 React 构建自定义着陆页。Docsbook 在 / 提供你的 README.md。如果你想要营销风格的着陆页，请单独托管该页面，并将 Docsbook 指向 docs.yourcompany.com，而不是 yourcompany.com。

版本管理#

Docusaurus 的 docs/versioned_docs/version-1.0/ 模式不受直接支持。选项：

• 为每个版本使用单独的 Docsbook 工作区（docsbook.io/yourorg/yourrepo-v1）
• 使用 Git 分支并切换被索引的分支
• 删除旧版本（大多数团队发现，他们只是出于习惯而维护这些版本）

时间#

• OSS 项目，约 80 个页面，最少的 MDX：2 小时
• 初创公司，约 300 个页面，中等程度的 MDX：半天
• 中期阶段，约 1000 个页面，大量 MDX：1–2 天

在决定迁移之前先进行测试。从同一代码仓库发布第二个网站不会产生任何费用，也不会改变仍在为读者提供服务的 Docusaurus 部署——如果结果未能达到一致，你所损失的只是进行测试所需的五秒钟。

免费开始 — 无需信用卡

下一步#

• 2026 年是否应该弃用 Docusaurus？ — 如果你还没有做出决定
• 2026 年 Docusaurus 替代方案：对比 9 个平台 — 更广泛的选择范围
• 为文档设置自定义域名 — 这次迁移中关于 DNS 和重定向的部分
• 文档即代码与托管平台的对比 — 迁移背后的原则