第13章 Docusaurus 1 到 2 迁移概览

Version: 2.x 迁移概览 本文档将引导你将现有的 Docusaurus 1 站点迁移到 Docusaurus 2。 我们力求简化这一过程，并提供了迁移 CLI 工具。 主要差异 Docusaurus 1 是一个纯粹的文档站点生成器，使用 React 作为服务端模板引擎，但不加载浏览器中的 React。 Docusaurus 2 是从底层重构的，它生成单页应用，充分利用了浏览器中 React 的功能。虽然它允许更高的可定制性，但保留了 Docusaurus 1 的精华部分——易上手、版本化文档以及 i18n。 除此之外，Docusaurus 2 是一个高性能的静态站点生成器，可以极快地用于创建常见的以内容驱动的站点（如文档、博客、产品落地页和营销页等）。 尽管我们的主要重点仍然是帮助你做好文档，但由于 Docusaurus 2 本质上就是一个 React 应用程序，因此你可以使用它构建任何类型的网站。Docusaurus 现在可用于构建任何网站，而不仅仅是文档站点。 Docusaurus 1 的结构 你的 Docusaurus 1 站点应具有以下结构： ├── docs
└── website
├── blog
├── core
│ └── Footer.js
├── package.json
├── pages
├── sidebars.json
├── siteConfig.js
└── static
Docusaurus 2 的结构 迁移完成后，你的 Docusaurus 2 站点可能如下所示： ├── docs
└── website
├── blog
├── src
│ ├── components
│ ├── css
│ └── pages
├── static
├── package.json
├── sidebars.json
├── docusaurus.config.js
提示此迁移不会改变 /docs 文件夹的位置，但 Docusaurus v2 站点通常把 /docs 文件夹放在 /website 目录内。迁移到 v2 后，你可以把 /docs 文件夹放在任意位置。 迁移流程​ 要得到一个完整可用的 Docusaurus 2 网站，需要迁移以下内容： packages CLI 命令 站点配置 Markdown 文件 侧边栏文件 页面、组件和 CSS 带版本的文档 i18n 支持 🚧 自动迁移流程​ 迁移 CLI 会帮你处理迁移中的大部分工作。 不过有些部分无法轻松自动化，仍需借助手动流程完成。 注意建议先运行迁移 CLI，再按手动迁移流程补全缺失的部分。 手动迁移流程​ 迁移中的某些部分无法自动化（尤其是页面），需要你手动迁移。 手动迁移指南提供了所有手动操作的步骤。 支持​ 如有任何问题，可以在 Discord 的 #migration-v1-to-v2 频道提问。 如果希望我们查看你的迁移 PR，可以在 PR 中 @slorber。 我们也有志愿者愿意帮助你迁移 v1 站点。 迁移 PR 示例​ 你可以参考我们为 Create React App 和 Flux 制作的迁移 PR，了解一个基础 Docusaurus v1 站点的迁移方式。