版本：2.2.0

手动迁移

This manual migration process should be run after the automated migration process, to complete the missing parts, or debug issues in the migration CLI output.

项目设置

`package.json`

包命名空间

在 Docusaurus 2 中，我们的包名都是有命名空间的：

docusaurus → @docusaurus/core

这允许我们把 Docusaurus 官方包和社区维护的包明确区分开来。换句话说，所有 Docusaurus 的官方包都会在 @docusaurus/ 命名空间下。

与此同时，Docusaurus 1 提供的默认文档站点功能现在由 @docusaurus/preset-classic 提供。所以我们也需要添加这个依赖项：

package.json
{
  dependencies: {
-   "docusaurus": "^1.x.x",
+   "@docusaurus/core": "^2.0.0-beta.0",
+   "@docusaurus/preset-classic": "^2.0.0-beta.0",
  }
}

提示

请使用最新的 Docusaurus 2 版本，你可以在这里查看（用 latest 标签）。

CLI 命令

与此同时，CLI 命令被重命名为了 docusaurus <command>（而不是 docusaurus-command）。

你的 package.json 的 "scripts" 部分应该更新为如下内容：

package.json
{
  "scripts": {
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy"
    // ...
  }
}

典型的 Docusaurus 2 package.json 一般看起来像这样：

package.json
{
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "serve": "docusaurus serve",
    "clear": "docusaurus clear"
  },
  "dependencies": {
    "@docusaurus/core": "^2.0.0-beta.0",
    "@docusaurus/preset-classic": "^2.0.0-beta.0",
    "clsx": "^1.1.1",
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  },
  "browserslist": {
    "production": [">0.5%", "not dead", "not op_mini all"],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

更新 `build` 目录的引用

在 Docusaurus 1 中，所有构建输出都位于 website/build/<项目名> 中。

在 Docusaurus 2 中，它现在变成了 website/build。确保你更新了部署配置，能够从正确的 build 目录中读取生成的文件。

如果你要部署到 GitHub pages，请务必运行 yarn deploy 而不是 yarn publish-gh-pages 脚本。

`.gitignore`

你的 website 文件夹的 .gitignore 应该包含：

.gitignore
# 依赖项
/node_modules

# 构建
/build

# 生成文件
.docusaurus
.cache-loader

# 其他
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*

`README`

D1 网站可能已经有一个 README 文件了。你可以修改它以反映 D2 的变更，也可以复制一份默认的 Docusaurus v2 README。

站点配置

`docusaurus.config.js`

把 siteConfig.js 重命名为 docusaurus.config.js。

在 Docusaurus 2 中，我们把每个功能（博客、文档、页面）都模块化成了一个插件。预设是一组插件的打包。为了向后兼容，我们制作了 @docusaurus/preset-classic 预设，它打包了 Docusaurus 1 中的大多数必需插件。

在你的 docusaurus.config.js 中添加如下预设配置：

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // 相对于站点目录的文档目录路径。
          path: '../docs',
          // 相对于站点目录的侧边栏文件。
          sidebarPath: require.resolve('./sidebars.json'),
        },
        // ...
      },
    ],
  ],
};

我们建议把 docs 目录移进 website 目录。v2 的默认文件结构也是这样的。 Vercel 开箱即用地支持 Docusaurus 项目部署，但前提是 docs 目录在 website 里面。一般来说，docs 在 website 里也要更好一点，把文档和其余的网站代码放在同一个 website 目录中，便于检索。

如果你正在迁移 Docusaurus v1 网站，但还有文档拉取请求未合并，你可以暂时把 /docs 文件夹保留在原来的位置，避免产生冲突。

下面的指南列出了 siteConfig.js 的每个字段以供参考。

已更新字段

`baseUrl`, `tagline`, `title`, `url`, `favicon`, `organizationName`, `projectName`, `githubHost`, `scripts`, `stylesheets`

无需操作，这些配置字段没有变化。

`colors`

已废弃。我们为 Docusaurus 2 编写了一个叫 Infima 的独立 CSS 框架，这个框架使用了 CSS 变量来做样式。文档还没有完工，完成后我们会在这里更新链接。要覆盖 Infima 的 CSS 变量，请创建你自己的 CSS 文件（比如 ./src/css/custom.css），把它作为 @docusaurus/preset-classic 的选项全局导入：

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        theme: {
          customCss: [require.resolve('./src/css/custom.css')],
        },
      },
    ],
  ],
};

Infima 每种颜色都使用 7 种色度。

/src/css/custom.css
/**
 * 你可以在这里覆盖默认的 Infima 变量。
 * 注意：这不是完整的 --ifm- 变量列表。
 */
:root {
  --ifm-color-primary: #25c2a0;
  --ifm-color-primary-dark: rgb(33, 175, 144);
  --ifm-color-primary-darker: rgb(31, 165, 136);
  --ifm-color-primary-darkest: rgb(26, 136, 112);
  --ifm-color-primary-light: rgb(70, 203, 174);
  --ifm-color-primary-lighter: rgb(102, 212, 189);
  --ifm-color-primary-lightest: rgb(146, 224, 208);
}

我们建议用 ColorBox 为你选择的主色调生成不同的色度。

或者，可以用下面的工具来生成不同的色度，然后把变量复制进 src/css/custom.css。

提示

Aim for at least WCAG-AA contrast ratio for the primary color to ensure readability. Use the Docusaurus website itself to preview how your color palette would look like. You can use alternative palettes in dark mode because one color doesn't usually work in both light and dark mode.

Primary Color:

Background:

CSS Variable Name	Hex	Adjustment	Contrast Rating
`--ifm-color-primary-lightest`	`#3cad6e`		Fail 🔴
`--ifm-color-primary-lighter`	`#359962`		Fail 🔴
`--ifm-color-primary-light`	`#33925d`		Fail 🔴
`--ifm-color-primary`	`#2e8555`	0	AA 👍
`--ifm-color-primary-dark`	`#29784c`		AA 👍
`--ifm-color-primary-darker`	`#277148`		AA 👍
`--ifm-color-primary-darkest`	`#205d3b`		AAA 🏅

Replace the variables in src/css/custom.css with these new variables.

/src/css/custom.css
:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  --ifm-color-primary-darker: #277148;
  --ifm-color-primary-darkest: #205d3b;
  --ifm-color-primary-light: #33925d;
  --ifm-color-primary-lighter: #359962;
  --ifm-color-primary-lightest: #3cad6e;
}

`footerIcon`, `copyright`, `ogImage`, `twitterImage`, `docsSideNavCollapsible`

网站元信息，比如资源、SEO、版权信息等，现在由主题处理。要自定义它们，可以使用 docusaurus.config.js 中的 themeConfig 字段：

docusaurus.config.js
module.exports = {
  // ...
  themeConfig: {
    footer: {
      logo: {
        alt: 'Meta 开源图标',
        src: '/img/meta_oss_logo.png',
        href: 'https://opensource.facebook.com/',
      },
      copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // 你也可以用自己的 HTML。
    },
    image: 'img/docusaurus.png',
    // ...
  },
};

`headerIcon`, `headerLinks`

在 Docusaurus 1 中，导航栏图标和导航栏链接是 siteConfig 中的根字段：

siteConfig.js
headerIcon: 'img/docusaurus.svg',
headerLinks: [
  { doc: "doc1", label: "上手" },
  { page: "help", label: "帮助" },
  { href: "https://github.com/", label: "GitHub" },
  { blog: true, label: "博客" },
],

现在，这些字段都是由主题处理的：

docusaurus.config.js
module.exports = {
  // ...
  themeConfig: {
    navbar: {
      title: 'Docusaurus',
      logo: {
        alt: 'Docusaurus 图标',
        src: 'img/docusaurus.svg',
      },
      items: [
        {to: 'docs/doc1', label: '上手', position: 'left'},
        {to: 'help', label: '帮助', position: 'left'},
        {
          href: 'https://github.com/',
          label: 'GitHub',
          position: 'right',
        },
        {to: 'blog', label: '博客', position: 'left'},
      ],
    },
    // ...
  },
};

`algolia`

docusaurus.config.js
module.exports = {
  // ...
  themeConfig: {
    algolia: {
      apiKey: '47ecd3b21be71c5822571b9f59e52544',
      indexName: 'docusaurus-2',
      algoliaOptions: { //... },
    },
    // ...
  },
};

注意

你的 Algolia DocSearch v1 配置（可以在这里找到）需要更新到 Docusaurus v2 的版本（范例）。

你可以联系 DocSearch 团队 (@shortcuts, @s-pace) 获取支持。他们可以帮你更新它，并触发你的网站的重新索引来恢复搜索（否则 24 小时后才能等到下次排定的索引）。

`blogSidebarCount`

已废弃。这些字段现在是 @docusaurus/preset-classic 的 blog 选项：

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          postsPerPage: 10,
        },
        // ...
      },
    ],
  ],
};

`cname`

已废弃。你可以在 static 文件夹中新建一个 CNAME 文件，然后填写你的自定义域名。 static 文件夹中的文件会在执行构建命令时被复制到 build 文件夹的根部。

`customDocsPath`, `docsUrl`, `editUrl`, `enableUpdateBy`, `enableUpdateTime`

重要变更：editUrl 应该指向 Docusaurus 项目（website 目录）而不是 docs 目录。

已废弃。这些字段现在是 @docusaurus/preset-classic 的 docs 选项：

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // 等价于 `customDocsPath`。
          path: 'docs',
          // 等价于 `editUrl` 但应该指向 `website` 目录而不是 `website/docs`。
          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
          // 等价于 `docsUrl`。
          routeBasePath: 'docs',
          // 传递给 MDX 的 Remark 和 Rehype 插件。 替代了 `markdownOptions` 和 `markdownPlugins`。
          remarkPlugins: [],
          rehypePlugins: [],
          // 等价于 `enableUpdateBy`。
          showLastUpdateAuthor: true,
          // 等价于 `enableUpdateTime`。
          showLastUpdateTime: true,
        },
        // ...
      },
    ],
  ],
};

`gaTrackingId`

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ...
        googleAnalytics: {
          trackingID: 'UA-141789564-1',
        },
      },
    ],
  ],
};

`gaGtag`

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // ...
        gtag: {
          trackingID: 'UA-141789564-1',
        },
      },
    ],
  ],
};

已移除字段

以下字段都已废弃，你可以从配置文件中移除。

blogSidebarTitle
cleanUrl - 现在 clean URL 默认启用。
defaultVersionShown - 版本化尚未完工。如果你有文档分版，你还不能迁移到 Docusaurus 2。敬请期待。
disableHeaderTitle
disableTitleTagline
docsSideNavCollapsible 现在是 docsPluginOptions.sidebarCollapsible，并且默认启用。
facebookAppId
facebookComments
facebookPixelId
fonts
highlight - 我们现在使用 Prism 而不是 highlight.js。
markdownOptions - 我们在 v2 中使用 MDX 而不是 Remarkable。你的 Markdown 选项必须转换为 Remak/Rehype 插件。
markdownPlugins - 我们在 v2 中使用 MDX 而不是 Remarkable。你的 Markdown 插件必须转换为 Remak/Rehype 插件。
manifest
onPageNav - 现在默认启用。
separateCss - 可以用类似上文提到的 custom.css 的方法导入。
scrollToTop
scrollToTopOptions
translationRecruitingLink
twitter
twitterUsername
useEnglishUrl
users
usePrism - 我们现在使用 Prism 而不是 highlight.js
wrapPagesHTML

我们打算在今后把许多废弃的配置字段作为插件实现。如果你愿意帮忙，我们不胜感激！

链接

In v1, all pages were available with or without the .html extension.

For example, these 2 pages exist:

If cleanUrl was:

true: links would target /installation
false: links would target /installation.html

In v2, by default, the canonical page is /installation, and not /installation.html.

If you had cleanUrl: false in v1, it's possible that people published links to /installation.html.

For SEO reasons, and avoiding breaking links, you should configure server-side redirect rules on your hosting provider.

As an escape hatch, you could use @docusaurus/plugin-client-redirects to create client-side redirects from /installation.html to /installation.

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-client-redirects',
      {
        fromExtensions: ['html'],
      },
    ],
  ],
};

If you want to keep the .html extension as the canonical URL of a page, docs can declare a slug: installation.html front matter.

组件

In previous version, nested sidebar category is not allowed and sidebar category can only contain doc ID. However, v2 allows infinite nested sidebar and we have many types of Sidebar Item other than document.

You'll have to migrate your sidebar if it contains category type. Rename subcategory to category and ids to items.

sidebars.json
{
- type: 'subcategory',
+ type: 'category',
  label: 'My Example Subcategory',
+ items: ['doc1'],
- ids: ['doc1']
},

website/core/Footer.js is no longer needed. If you want to modify the default footer provided by Docusaurus, swizzle it:

npm
Yarn
pnpm

npm run swizzle @docusaurus/theme-classic Footer

yarn swizzle @docusaurus/theme-classic Footer

pnpm run swizzle @docusaurus/theme-classic Footer

This will copy the current <Footer /> component used by the theme to a src/theme/Footer directory under the root of your site, you may then edit this component for customization.

Do not swizzle the Footer just to add the logo on the left. The logo is intentionally removed in v2 and moved to the bottom. Just configure the footer in docusaurus.config.js with themeConfig.footer:

module.exports = {
  themeConfig: {
    footer: {
      logo: {
        alt: 'Meta Open Source Logo',
        src: '/img/meta_oss_logo.png',
        href: 'https://opensource.facebook.com',
      },
    },
  },
};

页面

Please refer to creating pages to learn how Docusaurus 2 pages work. After reading that, notice that you have to move pages/en files in v1 to src/pages instead.

In Docusaurus v1, pages received the siteConfig object as props.

In Docusaurus v2, get the siteConfig object from useDocusaurusContext instead.

In v2, you have to apply the theme layout around each page. The Layout component takes metadata props.

CompLibrary is deprecated in v2, so you have to write your own React component or use Infima styles (Docs will be available soon, sorry about that! In the meanwhile, inspect the V2 website or view https://infima.dev/ to see what styles are available).

You can migrate CommonJS to ES6 imports/exports.

Here's a typical Docusaurus v2 page:

import React from 'react';
import Link from '@docusaurus/Link';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import Layout from '@theme/Layout';

const MyPage = () => {
  const {siteConfig} = useDocusaurusContext();
  return (
    <Layout title={siteConfig.title} description={siteConfig.tagline}>
      <div className="hero text--center">
        <div className="container ">
          <div className="padding-vert--md">
            <h1 className="hero__title">{siteConfig.title}</h1>
            <p className="hero__subtitle">{siteConfig.tagline}</p>
          </div>
          <div>
            <Link
              to="/docs/get-started"
              className="button button--lg button--outline button--primary">
              开始上手
            </Link>
          </div>
        </div>
      </div>
    </Layout>
  );
};

export default MyPage;

The following code could be helpful for migration of various pages:

Index page - Flux (recommended), Docusaurus 2, Hermes
Help/Support page - Docusaurus 2, Flux

内容

替换 AUTOGENERATED_TABLE_OF_CONTENTS

This feature is replaced by inline table of content

更新 Markdown 语法为 MDX 兼容语法

In Docusaurus 2, the Markdown syntax has been changed to MDX. Hence there might be some broken syntax in the existing docs which you would have to update. A common example is self-closing tags like <img> and <br> which are valid in HTML would have to be explicitly closed now ( <img/> and <br/>). All tags in MDX documents have to be valid JSX.

Front matter is parsed by gray-matter. If your front matter use special characters like :, you now need to quote it: title: Part 1: my part1 title → title: "Part 1: my part1 title".

Tips: You might want to use some online tools like HTML to JSX to make the migration easier.

多语言代码选项

Refer to the multi-language support code blocks section.

Front matter

The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.

The fields authorFBID and authorTwitter have been deprecated. They are only used for generating the profile image of the author which can be done via the authors field.

部署

The CNAME file used by GitHub Pages is not generated anymore, so be sure you have created it in /static/CNAME if you use a custom domain.

The blog RSS feed is now hosted at /blog/rss.xml instead of /blog/feed.xml. You may want to configure server-side redirects so that users' subscriptions keep working.

测试网站

After migration, your folder structure should look like this:

my-project
├── docs
└── website
    ├── blog
    ├── src
    │   ├── css
    │   │   └── custom.css
    │   └── pages
    │       └── index.js
    ├── package.json
    ├── sidebars.json
    ├── .gitignore
    ├── docusaurus.config.js
    └── static

Start the development server and fix any errors:

cd website
yarn start

You can also try to build the site for production:

yarn build

手动迁移

项目设置​

package.json​

包命名空间​

CLI 命令​

更新 build 目录的引用​

.gitignore​

README​

站点配置​

docusaurus.config.js​

已更新字段​

baseUrl, tagline, title, url, favicon, organizationName, projectName, githubHost, scripts, stylesheets​

colors​

footerIcon, copyright, ogImage, twitterImage, docsSideNavCollapsible​

headerIcon, headerLinks​

algolia​

blogSidebarCount​

cname​

customDocsPath, docsUrl, editUrl, enableUpdateBy, enableUpdateTime​

gaTrackingId​

gaGtag​

已移除字段​

链接​

组件​

侧边栏​

页脚​

页面​

内容​

替换 AUTOGENERATED_TABLE_OF_CONTENTS​

更新 Markdown 语法为 MDX 兼容语法​

多语言代码选项​

Front matter​

部署​

测试网站​