Skip to main content
Version: 3.5.1

概述

¥Overview

本文档将指导你将现有 Docusaurus 1 站点迁移到 Docusaurus 2。

¥This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2.

我们尝试让这一切变得尽可能简单，并提供迁移 CLI。

¥We try to make this as easy as possible, and provide a migration CLI.

主要区别​

¥Main differences

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

¥Docusaurus 1 is a pure documentation site generator, using React as a server-side template engine, but not loading React on the browser.

Docusaurus 2 从头开始重建，生成一个单页面应用，在浏览器中使用 React 的全部功能。它允许更多的可定制性，但保留了 Docusaurus 1 最好的部分 - 易于入门、版本化文档和 i18n。

¥Docusaurus 2, rebuilt from the ground up, generates a single-page-application, using the full power of React in the browser. It allows for more customizability but preserved the best parts of Docusaurus 1 - easy to get started, versioned docs, and i18n.

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

¥Beyond that, Docusaurus 2 is a performant static site generator and can be used to create common content-driven websites (e.g. Documentation, Blogs, Product Landing and Marketing Pages, etc) extremely quickly.

虽然我们的主要重点仍然是帮助你正确且良好地编写文档，但可以使用 Docusaurus 2 构建任何类型的网站，因为它只是一个 React 应用。Docusaurus 现在可用于构建任何网站，而不仅仅是文档网站。

¥While our main focus will still be helping you get your documentations right and well, it is possible to build any kind of website using Docusaurus 2 as it is just a React application. Docusaurus can now be used to build any website, not just documentation websites.

Docusaurus 1 结构​

¥Docusaurus 1 structure

你的 Docusaurus 1 站点应具有以下结构：

¥Your Docusaurus 1 site should have the following structure:

├── docs
└── website
    ├── blog
    ├── core
    │   └── Footer.js
    ├── package.json
    ├── pages
    ├── sidebars.json
    ├── siteConfig.js
    └── static

Docusaurus 2 结构​

¥Docusaurus 2 structure

迁移后，你的 Docusaurus 2 站点可能如下所示：

¥After the migration, your Docusaurus 2 site could look like:

├── docs
└── website
    ├── blog
    ├── src
    │   ├── components
    │   ├── css
    │   └── pages
    ├── static
    ├── package.json
    ├── sidebars.json
    ├── docusaurus.config.js
信息

此迁移不会更改 /docs 文件夹位置，但 Docusaurus v2 站点通常在 /website 内具有 /docs 文件夹

¥This migration does not change the /docs folder location, but Docusaurus v2 sites generally have the /docs folder inside /website

迁移到 v2 后，你可以随意将 /docs 文件夹放置在任意位置。

¥You are free to put the /docs folder anywhere you want after having migrated to v2.

迁移过程​

¥Migration process

要获得功能齐全的 Docusaurus 2 网站，需要迁移多种内容：

¥There are multiple things to migrate to obtain a fully functional Docusaurus 2 website:

  • packages

  • CLI 命令

    ¥CLI commands

  • 站点配置

    ¥site configuration

  • Markdown 文件

    ¥Markdown files

  • 侧边栏文件

    ¥sidebars file

  • 页面、组件和 CSS

    ¥pages, components and CSS

  • 版本化文档

    ¥versioned docs

  • 国际化支持 🚧

    ¥i18n support 🚧

自动迁移过程​

¥Automated migration process

迁移 CLI 将为你处理迁移中的许多事情。

¥The migration CLI will handle many things of the migration for you.

但是，某些部分无法轻松实现自动化，你将不得不退回到手动流程。

¥However, some parts can't easily be automated, and you will have to fallback to the manual process.

注意

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

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

手动迁移过程​

¥Manual migration process

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

¥Some parts of the migration can't be automated (particularly the pages), and you will have to migrate them manually.

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

¥The manual migration guide will give you all the manual steps.

支持​

¥Support

有任何问题都可以在 #migration-v1-to-v2 Discord 通道 中提问。

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

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

¥Feel free to tag @slorber in any migration PRs if you would like us to have a look.

我们还有愿意 帮助你迁移 v1 网站 的志愿者。

¥We also have volunteers willing to help you migrate your v1 site.

迁移 PR 示例​

¥Example migration PRs

你可能需要参考我们针对 Create React App 和 Flux 的迁移 PR，作为如何完成基本 Docusaurus v1 站点迁移的示例。

¥You might want to refer to our migration PRs for Create React App and Flux as examples of how a migration for a basic Docusaurus v1 site can be done.