跳到主要内容
版本：2.2.0

Legacy GitBook 迁移至 Docusaurus 技术方案

基于将现有 Legacy GitBook 迁移至 Docusaurus 的需求，本方案详细说明了如何平滑过渡，并完全满足以下 6 项核心要求：

1. 需求对齐与能力映射​

需求点Docusaurus 解决方案状态
1. 多版本切换原生支持。通过内置的 Versioning 机制，一键生成快照，自带右上角版本切换下拉框。✅ 完美支持
2. GitBook 基本功能导航 (sidebars.js)、代码高亮 (Prism.js)、Markdown 扩展等全部内置。本地搜索可引入第三方插件。✅ 完全覆盖
3. Markdown 渲染静态 HTML底层基于 React，通过 npm run build 命令将 Markdown/MDX 预渲染为纯静态的 HTML/CSS/JS。✅ 完美支持
4. 支持本地部署构建产物 (build/ 目录) 为纯静态文件，可直接放入 Nginx、IIS、Apache 等任何 Web 服务器。✅ 完美支持
5. 主动拉取 Git 更新Docusaurus 是静态生成器，拉取 Git 属于持续集成（CI/CD）范畴。可通过提供 Shell 脚本 + Crontab/Webhook 的方式实现自动拉取与重新构建。✅ 脚本支持
6. 正确显示 Mermaid 图表官方自 v2.1.0 起提供 @docusaurus/theme-mermaid 主题，原生解析 Markdown 中的 Mermaid 代码块。✅ 原生插件

2. 核心迁移步骤​

步骤 1：初始化 Docusaurus 项目​

在你希望放置新文档的目录中执行：

npx create-docusaurus@latest my-website classic
cd my-website

步骤 2：迁移文档内容​

  1. 将当前 docs/GitBook/content/ 下的所有 Markdown 文件，直接拷贝到 Docusaurus 的 docs/ 目录中。
  2. 将图片资源 (assets/) 拷贝到 Docusaurus 的 static/img/ 或与 Markdown 文件同级的目录。

步骤 3：转换目录结构 (SUMMARY.md -> sidebars.js)​

GitBook 使用 SUMMARY.md 生成左侧菜单，而 Docusaurus 使用 sidebars.js。你需要将层级关系转换为 JSON 对象。 示例 sidebars.js:

module.exports = {
  tutorialSidebar: [
    'README', // 对应 docs/README.md
    {
      type: 'category',
      label: '基础文档',
      items: ['基础文档/配置', '基础文档/事务'], 
    },
    {
      type: 'category',
      label: '其他',
      items: ['其他/Linux部署', '其他/IIS应用程序池配置'],
    },
  ],
};

3. 关键功能配置​

3.1 多版本支持 (Versioning)​

当你准备发布 v1.0 时，只需运行：

npm run docusaurus docs:version 1.0

Docusaurus 会自动将当前 docs/ 下的所有文件复制一份存入 versioned_docs/version-1.0/，并锁定内容。你在 docs/ 下的修改将作为 "Next" (通常是 v2.0 草稿) 版本。页面右上角会自动出现版本切换器。

3.2 启用 Mermaid 图表支持​

  1. 安装官方依赖：
npm install --save @docusaurus/theme-mermaid
  1. 修改 docusaurus.config.js：
module.exports = {
  // ...
  markdown: {
    mermaid: true, // 开启 Mermaid
  },
  themes: ['@docusaurus/theme-mermaid'],
};

3.3 替换 GitBook 搜索功能​

Docusaurus 官方推荐 Algolia (需联网)，但为了纯本地部署，我们需要使用本地搜索插件。

  1. 安装插件：
npm install --save @cmfcmf/docusaurus-search-local
  1. 在 docusaurus.config.js 注册：
plugins: [
  [
    require.resolve("@cmfcmf/docusaurus-search-local"),
    {
      language: "zh", // 支持中文分词
    },
  ],
],

4. 本地部署与自动拉取 Git 更新方案​

由于纯静态文件无法自己执行 Git 命令，我们需要在**本地服务器（如 Linux/CentOS）**上配置一个自动化脚本。

4.1 编写更新与构建脚本 (update-docs.sh)​

在项目根目录创建一个 Bash 脚本：

#!/bin/bash
# 路径指向你的文档仓库
PROJECT_DIR="/path/to/your/docusaurus/repo"
BUILD_DIR="$PROJECT_DIR/build"
NGINX_HTML="/usr/share/nginx/html/docs" # 你的 IIS 或 Nginx 部署目录

cd $PROJECT_DIR

# 1. 拉取最新代码
echo "Pulling latest code from Git..."
git pull origin main

# 2. 安装依赖 (如果 package.json 没变，这一步很快)
npm install

# 3. 重新构建静态 HTML
echo "Building Docusaurus..."
npm run build

# 4. 将产物同步到 Web 服务器目录
echo "Deploying to web server..."
rsync -av --delete $BUILD_DIR/ $NGINX_HTML/

echo "Update complete!"

4.2 触发方式 (两种可选)​

方式 A：定时化拉取 (Crontab) - 最简单 如果你不介意几分钟的延迟，可以在服务器设置定时任务，每 5 分钟检查一次。

# 执行 crontab -e 添加：
*/5 * * * * /bin/bash /path/to/update-docs.sh >> /var/log/update-docs.log 2>&1

(优化：可以在脚本中判断 git pull 是否有变更，有变更才执行 npm run build 以节省性能)

方式 B：Git Webhook (主动推送) - 最实时

  1. 在本地服务器运行一个轻量级的 Node.js 监听服务 (如使用 webhook 库或 express)。
  2. 在 Gitee / GitLab / GitHub 的仓库设置中配置 Webhook，指向你的本地服务器 IP (例如 http://your-ip:9000/hooks/update-docs)。
  3. 当有人 Push 代码到仓库时，触发 Webhook，Node.js 接收到请求后执行上述 update-docs.sh。

5. 总结​

采用 Docusaurus + Local Search Plugin + Mermaid Theme + Webhook/Cron 脚本 的组合，可以完美替代现有的 GitBook。它彻底解决了旧版 GitBook 缺乏多版本管理的问题，同时保留了 Markdown 的编写体验和纯本地部署的安全性。