跳到主要内容

概述

本文档将指导您将现有的 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
  • 版本化文档
  • 国际化支持 🚧

自动迁移过程​

迁移 CLI 将为您处理迁移的许多方面。

然而，有些部分无法轻松自动化，您将不得不回退到手动过程。

备注

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

手动迁移过程​

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

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

支持​

对于任何问题，您可以在 #migration-v1-to-v2 Discord 频道中提问。

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

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

示例迁移 PR​

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