概述

本文档将指导您如何将现有的 Docusaurus 1 站点迁移到 Docusaurus 2。

我们力求使其尽可能简单，并提供一个迁移 CLI。

主要区别

Docusaurus 1 是一个纯文档站点生成器，使用 React 作为服务器端模板引擎，但不在浏览器上加载 React。

Docusaurus 2 从头开始重建，生成一个单页应用程序，在浏览器中充分利用 React 的强大功能。它提供了更高的可定制性，同时保留了 Docusaurus 1 的最佳部分——易于上手、版本化文档和国际化支持。

除此之外，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 将为您处理许多迁移事项。

然而，某些部分无法轻易自动化，您需要回退到手动过程。

注意

我们建议运行迁移 CLI，并通过手动迁移过程来补全缺失的部分。

手动迁移过程

迁移的某些部分无法自动化（特别是页面），您将不得不手动迁移它们。

手动迁移指南将为您提供所有手动步骤。

支持

如有任何疑问，您可以在 Discord 频道 #migration-v1-to-v2 中提问。

如果您希望我们查看任何迁移 PR，请随时在其中提及 @slorber。

我们也有志愿者愿意帮助您迁移 v1 站点。

示例迁移 PR

您可以参考我们为 Create React App 和 Flux 所做的迁移 PR，作为如何进行 Docusaurus v1 站点基本迁移的示例。