从 VuePress 1 迁移到 Docusaurus 2

[lmk123]

最近花了点时间将划词翻译的文档站从 VuePress 1 迁移到了 Docusaurus 2（类似于 VuePress，它是基于 React 的静态网站生成器）。

我将迁移过程和一些不同之处做了总结，希望能帮到跟我一样需要迁移的同学。

为什么要迁移？

在刚开始开发划词翻译 v7 的时候，我用的是 Vue.js，当时 Vue.js 3 还没有发布，于是自然而然的就用 VuePress 1 搭建了文档站，即使后来我改为使用 React Hooks 开发了划词翻译 v7，文档站也一直延用至今。

最近，我想在文档站上展示一些业务相关的页面，比如注册 / 登录、用户后台、活动页面等。现在，我有 3 个选择：

1. 直接在 VuePress 1 上开发这些页面。
2. 从 VuePress 1 迁移到 VuePress 2。
3. 从 VuePress 1 迁移到 Docusaurus 2。

VuePress 1 是基于 Vue.js 2 的，但 Vue.js 3 已经发布了，所以第 1 点我就不考虑了；剩下的选择中，我更倾向于第 3 点，这样能统一划词翻译与文档站的技术栈，它们之间就可以共用代码了。虽然迁移成本可能会比第 2 点高，但我还是决定尝试一下。

开始迁移

我迁移的大致步骤是：

1. 先创建一个 Docusaurus 项目
2. 将 Markdown 文件复制进项目中
3. 运行项目看看有哪些报错

Docusaurus 的报错非常详细，所以定位问题很方便。在迁移过程中，我主要做了下面这些更改。

文档地址不同

VuePress 1 和 Docusaurus 都将文档放在 docs 目录下，但是它们生成的 URL 是不同的。

在 VuePress 1 中，目录下的文件是相对于网站根目录的，例如，docs/README.md 会生成 /index.html、docs/guide/intro.md 会生成 /guide/intro.html。

在 Docusaurus 中，生成的路径是带 /docs 前缀的，且没有 .html 后缀，README.md 也不会自动转为 index。也就是说，docs/README.md 会生成 /docs/README、docs/guide/intro.md 会生成 /docs/guide/intro。

为了让以前的链接仍然生效，需要对以前的 URL 做跳转，例如将 /guide/intro.html 跳转到 /docs/guide/intro。

静态文件地址不同

在 VuePress 1 中，静态文件都存放在 docs/.vueprsss/public 文件夹下，而 Docusaurus 存放在 static 文件夹下，所以 Markdown 里引用的静态文件路径需要修改。

JSX vs HTML

VuePress 1 可以直接在 Markdown 里写 HTML，但是 Docusaurus 用的是 MDX 的语法，在 Markdown 里只能写 JSX，而 JSX 跟 HTML 是有区别的，例如：

• JSX 的属性名称是驼峰式的。例如，我需要将 colspan 改为 colSpan。
• JSX 的标签必须闭合。例如，我需要将 <img src="..."> 改为 <img src="..." />。
• 组件引入。VuePress 1 需要把组件放在特定的文件夹中，在 Markdown 里就可以直接使用，但是 Docusaurus 需要将组件 import 进 Markdown。

Markdown 扩展语法 - 自定义容器

VuePress 1 中的自定义容器跟 Docusaurus 是不同的：

• Docusaurus 的语法中，::: 与容器类型之间没有空格，例如在 VuePress 1 里写 ::: tip 提示，在 Docusaurus 要改成 :::tip 提示。
• VuePress 1 的 ::: warning 需要改成 :::caution。
• Docusaurus 不支持 ::: details，我改成了 :::note。

侧边栏

侧边栏的配置有些许不同，但也不难理解。最大的不同在于，VuePress 1 会将 TOC 作为侧边栏的一部分，而 Docusaurus 的 TOC 是显示在页面右侧的，不是作为左侧的侧边栏的一部分。这样做的好处有：

• 侧边栏的高度变小了。
• Docusaurus 的侧边栏配置更简单。配置在侧边栏里的文档就显示侧边栏，没有配置的就不显示。如果要在 VuePress 1 里做到这一点，需要用 sidebar: false 等一些配置，相比之下，Docusaurus 的做法更直观。

站内搜索

VuePress 1 有一个官方的支持站内搜索的插件。Docusaurus 只内置了 Algolia DocSearch 的搜索服务，但是我在相关资源里找到了 @easyops-cn/docusaurus-search-local——这是目前为止我发现的唯一一个支持中文的搜索插件。

i18n

在 VuePress 1 中，官方主题的一些文字提示是用英文写的，但是可以在配置文件中修改，例如我就将 Last Updated 和 Edit this page on GitHub 修改为了 上次更新 和 在 GitHub 上编辑此页。在 Docusaurus 中，i18n 的体验要更好一些。

一开始，我不知道 Docusaurus 的官方主题是自带中文的，但自行修改也不是难事。只需要运行 yarn run write-translations 就会生成一些 JSON 文件，在 JSON 文件里修改对应的 message 就可以了。这样，i18n 跟配置文件就是相互独立的，不会都混杂在同一个配置文件里了。

后来在看官方主题的源码时，我发现官方主题是有 zh-Hans.json 的中文翻译的，看到这个文件的名称我就明白了：defaultLocale 需要设置为 zh-Hans 才能应用这份配置，而我一开始设置的是 zh——官方主题找不到 zh.json，所以默认使用了英文。

Docusaurus 的文档里没有提到这一点，所以这也算是踩的一个坑吧。

迁移后的改进

完成以上的修改后，文档站就已经迁移完成了，但是，我发现 Docusaurus 还支持一些额外的功能可以用来改进文档站。

内置的博客系统

Docusaurus 的官方主题同时支持文档和博客。在 VuePress 1 中，官方主题只支持文档，虽然另外有一个博客主题，但是文档和博客是不能同时存在的。对于我而言，我偶尔是需要写一些跟划词翻译相关的博客的，比如功能有重大变更时给用户看的公告。

自定义 Header Anchors

VuePress 1 和 Docusaurus 都会自动给标题生成一个 id，但是 Docusaurus 支持自定义 id，就像这样：

## 我是标题 {#custom-id}

这样能解决很多问题：

• 用中文写的标题在 VuePress 1 中生成的 id 会导致控制台报错：Failed to execute 'querySelector' on 'Document': '#%E9%93%BE%E6%8E%A5' is not a valid selector.。
• 在 VuePress 1 中，如果要自定义 id，那么按照 VuePress 1 的文档，只能修改 Markdown 渲染函数，而不是针对每个标题单独指定。但是，标题的内容是可能变化的，如果我想在修改标题内容后保持 id 不变，似乎很麻烦。

相比之下，Docusaurus 的方式就好多了。

使用体验

在用了一段时间 Docusaurus 之后，我个人觉得使用体验是比 VuePress 1 要好一些的。

Docusaurus 支持 yarn serve 命令，可以在 build 之后使用生产环境的文件测试网站的展示情况。虽然这其实就是一个本地的文件服务器，但内建到工作流中比自己通过其它方式运行要便捷很多。

Docusaurus 会自动检查文档内有没有坏链，这让我的迁移过程简单了很多。

Docusaurus 的官方主题还默认支持深色模式，这对于我这种喜欢半夜写代码的人来说太友好了。

[ice1000]

大佬怎么看待 vitepress 和 vuepress 2 的预览版？我感觉 vitepress 还行，官方说是要尽可能轻量，我是前端小白，在我用到的场景体验都差不多，倒是 vuepress 2 遇到了些迁移问题。

支持站内搜索厉害了。我用 vitepress 的时候站内搜索是 react 写的，就没配置了。

[lmk123]

vitepress 和 vuepress 2 我都没用过，没法提供建议 😂