迁移概览

此文档将教授您如何将现有的 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 网站：

• 软件包
• CLI 命令
• 站点配置
• Markdown 文件
• 侧边栏文件
• 页面、 组件和 CSS
• 分版文档
• i18n 支持🚧

自动迁移流程

迁移 CLI 工具会为你处理许多迁移中的问题。

但是，有些功能无法自动迁移，您需要手动迁移。

备注

We recommend running the migration CLI, and complete the missing parts thanks to the manual migration process.

手动迁移流程

部分迁移流程无法自动完成（特别是页面部分），您需要进行手动迁移。

手动迁移 将为你列出所有手动迁移所需的步骤。

支持

For any questions, you can ask in the #migration-v1-to-v2 Discord channel.

若您需要我们审查，请在您的迁移合并请求中 @slorber。

我们还有志愿者帮助您迁移您的 v1 站点。

迁移合并请求示例

您可以参考我们为 Create React App 和 Flux 提交的迁移合并请求来了解如何迁移简单的 Docusaurus v1 网站。