手动迁移

在运行 自动化迁移流程 之后，应运行此手动迁移流程，以完成缺失的部分或调试迁移 CLI 输出中的问题。

项目设置

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/<PROJECT_NAME> 中。

在 Docusaurus 2 中，它现在已移动到 website/build。确保您更新部署配置以从正确的 build 目录读取生成的 files。

如果您部署到 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: {
          // Docs 文件夹路径相对于网站目录。
          path: '../docs',
          // Sidebars 文件相对于网站目录。
          sidebarPath: require.resolve('./sidebars.json'),
        },
        // ...
      },
    ],
  ],
};

我们建议将 docs 文件夹移动到 website 文件夹中，这也是 v2 中的默认目录结构。如果 docs 目录位于 website 中， Vercel 支持 开箱即用的 Docusaurus 项目部署 。通常最好将文档放在网站内部，以便文档和网站其余代码位于同一个 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 Open Source Logo',
        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: "Getting Started" },
  { page: "help", label: "Help" },
  { href: "https://github.com/", label: "GitHub" },
  { blog: true, label: "Blog" },
],

现在，这两个字段都由主题处理：

docusaurus.config.js

module.exports = {
  // ...
  themeConfig: {
    navbar: {
      title: 'Docusaurus',
      logo: {
        alt: 'Docusaurus Logo',
        src: 'img/docusaurus.svg',
      },
      items: [
        {to: 'docs/doc1', label: 'Getting Started', position: 'left'},
        {to: 'help', label: 'Help', position: 'left'},
        {
          href: 'https://github.com/',
          label: 'GitHub',
          position: 'right',
        },
        {to: 'blog', label: 'Blog', 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：

docusaurus.config.js

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

cname

已弃用。改为在您的 static 文件夹中创建一个包含您自定义域的 CNAME 文件。在执行构建命令期间，static 文件夹中的文件将被复制到 build 文件夹的根目录中。

customDocsPath、docsUrl、editUrl、enableUpdateBy、enableUpdateTime

重大更改: editUrl 应指向 (网站) Docusaurus 项目而不是 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 - 现在默认使用干净的 URL。
• defaultVersionShown - 版本控制功能尚未移植。如果您正在使用版本控制，则无法迁移到 Docusaurus 2。敬请关注。
• disableHeaderTitle
• disableTitleTagline
• docsSideNavCollapsible 可在 docsPluginOptions.sidebarCollapsible 中使用，并且现在默认启用。
• facebookAppId
• facebookComments
• facebookPixelId
• fonts
• highlight - 我们现在使用 Prism 而不是 highlight.js 。
• markdownOptions - 我们在 v2 中使用 MDX 而不是 Remarkable。您的 Markdown 选项必须转换为 Remark/Rehype 插件。
• markdownPlugins - 我们在 v2 中使用 MDX 而不是 Remarkable。您的 Markdown 插件必须转换为 Remark/Rehype 插件。
• manifest
• onPageNav - 此功能现在默认启用。
• separateCss - 它可以像上面提到的 custom.css 一样导入。
• scrollToTop
• scrollToTopOptions
• translationRecruitingLink
• twitter
• twitterUsername
• useEnglishUrl
• users
• usePrism - 我们现在使用 Prism 而不是 highlight.js
• wrapPagesHTML

我们打算在未来将许多已弃用的配置字段实现为插件。欢迎您的帮助！

URL

在 v1 中，所有页面都可以使用或不使用 .html 扩展名。

例如，存在这两个页面：

• https://v1.docusaurus.io/docs/en/installation
• https://v1.docusaurus.io/docs/en/installation.html

如果 cleanUrl 为：

• true: 链接将指向 /installation
• false: 链接将指向 /installation.html

在 v2 中，默认情况下，规范页面是 /installation，而不是 /installation.html。

如果您在 v1 中使用 cleanUrl: false，则人们可能发布了指向 /installation.html 的链接。

出于 SEO 原因，并避免破坏链接，您应该在您的托管提供商上配置服务器端重定向规则。

作为应急措施，您可以使用 @docusaurus/plugin-client-redirects 从 /installation.html 创建客户端重定向到 /installation。

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

如果您想保留 .html 扩展名作为页面的规范 URL，文档可以声明 slug: installation.html 前端内容。

组件

侧边栏

在之前的版本中，不允许嵌套侧边栏类别，侧边栏类别只能包含文档 ID。但是，v2 允许无限嵌套侧边栏，并且我们有很多类型的 侧边栏项目 ，而不仅仅是文档。

如果您的侧边栏包含类别类型，则必须迁移您的侧边栏。将 subcategory 重命名为 category，将 ids 重命名为 items。

sidebars.json

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

页脚

website/core/Footer.js 不再需要。如果您想修改 Docusaurus 提供的默认页脚，请 swizzle 它：

npm

npm run swizzle @docusaurus/theme-classic Footer

Yarn

yarn swizzle @docusaurus/theme-classic Footer

pnpm

pnpm run swizzle @docusaurus/theme-classic Footer

这会将主题使用的当前 <Footer /> 组件复制到您网站根目录下的 src/theme/Footer 目录，然后您可以编辑此组件以进行自定义。

不要仅仅为了在左侧添加徽标而 swizzle 页脚。徽标在 v2 中故意移除并移动到底部。只需使用 themeConfig.footer 在 docusaurus.config.js 中配置页脚：

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

页面

请参考 创建页面 了解 Docusaurus 2 页面的工作原理。阅读之后，请注意您必须将 v1 中的 pages/en 文件移动到 src/pages。

在 Docusaurus v1 中，页面接收 siteConfig 对象作为 props。

在 Docusaurus v2 中，改为从 useDocusaurusContext 获取 siteConfig 对象。

在 v2 中，您必须在每个页面周围应用主题布局。Layout 组件采用元数据 props。

CompLibrary 在 v2 中已弃用，因此您必须编写自己的 React 组件或使用 Infima 样式（文档很快就会提供，对此表示歉意！同时，请检查 V2 网站或查看 https://infima.dev/ 以查看可用的样式）。

您可以将 CommonJS 迁移到 ES6 导入/导出。

这是一个典型的 Docusaurus v2 页面：

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">
              Get started
            </Link>
          </div>
        </div>
      </div>
    </Layout>
  );
};

export default MyPage;

以下代码可能对各种页面的迁移有所帮助：

• 首页 - Flux （推荐）、 Docusaurus 2 、Hermes
• 帮助/支持页面 - Docusaurus 2 、Flux

内容

替换 AUTOGENERATED_TABLE_OF_CONTENTS

此功能已由 内联目录 替换。

更新 Markdown 语法以使其与 MDX 兼容

在 Docusaurus 2 中，Markdown 语法已更改为 MDX 。因此，现有文档中可能存在一些损坏的语法，您需要更新这些语法。一个常见的例子是自闭合标签，如 <img> 和 <br>，它们在 HTML 中有效，现在必须显式关闭（<img/> 和 <br/>）。MDX 文档中的所有标签都必须是有效的 JSX。

前端内容由 gray-matter 解析。如果您的前端内容使用特殊字符（如 :），您现在需要用引号括起来：title: Part 1: my part1 title → title: "Part 1: my part1 title"。

提示: 您可能需要使用一些在线工具，例如 HTML to JSX ，以使迁移更容易。

特定语言的代码选项卡

请参考 多语言支持代码块 部分。

前端内容

博客的 Docusaurus 前端内容字段已从 camelCase 更改为 snake_case，以与文档保持一致。

字段 authorFBID 和 authorTwitter 已弃用。它们仅用于生成作者的个人资料图片，这可以通过 authors 字段完成。

部署

GitHub Pages 使用的 CNAME 文件不再生成，因此如果您使用自定义域，请确保已在 /static/CNAME 中创建它。

博客 RSS 订阅源现在位于 /blog/rss.xml 而不是 /blog/feed.xml。您可能需要配置服务器端重定向，以便用户的订阅继续工作。

测试您的站点

迁移后，您的文件夹结构应如下所示：

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

启动开发服务器并修复任何错误：

npm

cd website
npm start

Yarn

cd website
yarn start

pnpm

cd website
pnpm start

您还可以尝试构建用于生产的站点：

npm

npm run build

Yarn

yarn build

pnpm

pnpm run build