手动迁移

这个手动迁移过程应该在自动迁移过程之后运行，以完成缺失的部分，或调试迁移 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"
    ]
  }
}

更新构建目录的引用

在 Docusaurus 1 中，所有构建产物都位于 website/build/<PROJECT_NAME> 中。

在 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 内。将文档放在网站内通常更好，因为文档和网站的其余代码位于同一个 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.`, // You can also put own HTML here.
    },
    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

BREAKING: editUrl 应该指向（网站）Docusaurus 项目，而不是 docs 目录。

已弃用。将其作为选项传递给 @docusaurus/preset-classic 的 docs：

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // Equivalent to `customDocsPath`.
          path: 'docs',
          // Equivalent to `editUrl` but should point to `website` dir instead of `website/docs`.
          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
          // Equivalent to `docsUrl`.
          routeBasePath: 'docs',
          // Remark and Rehype plugins passed to MDX. Replaces `markdownOptions` and `markdownPlugins`.
          remarkPlugins: [],
          rehypePlugins: [],
          // Equivalent to `enableUpdateBy`.
          showLastUpdateAuthor: true,
          // Equivalent to `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 - 我们使用 MDX 而不是 Remarkable。您的 Markdown 选项必须转换为 Remark/Rehype 插件。
• markdownPlugins - 我们使用 MDX 而不是 Remarkable。您的 Markdown 插件必须转换为 Remark/Rehype 插件。
• manifest
• onPageNav - 现在默认启用。
• separateCss - 它可以通过与上面提到的 custom.css 相同的方式导入。
• scrollToTop
• scrollToTopOptions
• translationRecruitingLink
• twitter
• twitterUsername
• useEnglishUrl
• users
• usePrism - 我们现在使用 Prism 而不是 highlight.js
• wrapPagesHTML

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

Urls

在 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'],
      },
    ],
  ],
};

如果您希望保留页面作为规范 URL 的 .html 扩展名，则 docs 可以声明一个 slug: installation.html front matter。

Components

Sidebar

在以前的版本中，不允许嵌套侧边栏类别，侧边栏类别只能包含文档 ID。然而，v2 允许无限嵌套侧边栏，并且我们有多种类型的 Sidebar Item 而不是文档。

您需要迁移侧边栏，如果它包含类别类型。将 subcategory 重命名为 category，并将 ids 重命名为 items。

sidebars.json

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

Footer

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

Bun

bun run swizzle @docusaurus/theme-classic Footer

这将复制当前在主题中使用的 <Footer /> 组件到 src/theme/Footer 目录下的根目录，您可以在此组件上进行自定义。

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

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

Pages

请参考 创建页面 以了解 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;

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

• Index 页面 - Flux（推荐），Docusaurus 2，Hermes
• Help/Support 页面 - Docusaurus 2，Flux

Content

替换 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 使迁移更容易。

Language-specific code tabs

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

Front matter

Docusaurus 博客的前言字段已从 camelCase 更改为 snake_case，以保持一致性。

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

Deployment

CNAME 文件用于 GitHub Pages 不再生成，因此请确保您已在 /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

Bun

cd website
bun start

您还可以尝试为生产构建网站：

npm

npm run build

Yarn

yarn build

pnpm

pnpm run build

Bun

bun run build