概述

本指南将引导您完成将现有 Docusaurus 1 网站迁移到 Docusaurus 2 的过程。

我们努力使这个过程尽可能简单，并提供了一个迁移命令行工具。

主要区别

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

Docusaurus 2 从头开始重建，生成一个单页应用程序，在浏览器中使用 React 的全部功能。它允许进行更多自定义，但保留了 Docusaurus 1 最好的部分——易于上手、版本化文档和国际化支持。

除此之外，Docusaurus 2 是一个 高性能的静态站点生成器 ，可以用来极其快速地创建常见的基于内容的网站（例如文档、博客、产品着陆页和营销页面等）。

虽然我们的主要关注点仍然是帮助您正确且完善地编写文档，但由于它只是一个 React 应用程序，因此可以使用 Docusaurus 2 构建任何类型的网站。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 网站，需要迁移多个方面：

• 包
• 命令行工具命令
• 站点配置
• Markdown 文件
• 侧边栏文件
• 页面、组件和 CSS
• 版本化文档
• 国际化支持 🚧

自动化迁移过程

迁移命令行工具 将为您处理许多迁移工作。

但是，有些部分不容易自动化，您将不得不回退到手动流程。

备注

我们建议运行迁移命令行工具，并通过手动迁移过程完成缺失的部分。

手动迁移过程

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

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

支持

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

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

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

示例迁移 PR

您可能想参考我们针对 Create React App 和 Flux 的迁移 PR，这些 PR 是如何完成基本 Docusaurus v1 站点迁移的示例。