手动迁移

此手动迁移过程应在自动化迁移过程之后运行，以补充遗漏部分或调试迁移 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 目录读取生成的文件。

如果您正在部署到 GitHub Pages，请确保运行 yarn deploy 而不是 yarn publish-gh-pages 脚本。

.gitignore

您的 website 文件夹中的 .gitignore 应包含

.gitignore

# dependencies
/node_modules

# production
/build

# generated files
.docusaurus
.cache-loader

# misc
.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 folder path relative to website dir.
          path: '../docs',
          // Sidebars file relative to website dir.
          sidebarPath: require.resolve('./sidebars.json'),
        },
        // ...
      },
    ],
  ],
};

我们建议将 docs 文件夹移动到 website 文件夹中，这也是 v2 中的默认目录结构。Vercel 如果 docs 目录在 website 内，则开箱即用支持 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

/**
 * You can override the default Infima variables here.
 * Note: this is not a complete list of --ifm- variables.
 */
: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 中。

提示

主色应至少达到 WCAG-AA 对比度，以确保可读性。使用 Docusaurus 网站本身来预览您的调色板外观。您可以在暗模式下使用替代调色板，因为一种颜色通常不能同时在亮模式和暗模式下良好工作。

主色

背景

CSS 变量名	十六进制	调整	对比度评级
--ifm-color-primary-lightest	#3cad6e		失败 🔴
--ifm-color-primary-lighter	#359962		失败 🔴
--ifm-color-primary-light	#33925d		失败 🔴
--ifm-color-primary	#2e8555	0	AA 👍
--ifm-color-primary-dark	#29784c		AA 👍
--ifm-color-primary-darker	#277148		AA 👍
--ifm-color-primary-darkest	#205d3b		AAA 🏅

将 src/css/custom.css 中的变量替换为这些新变量。

/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

重大变更：editUrl 应指向（网站）Docusaurus 项目，而不是 docs 目录。

已弃用。请改为将其作为选项传递给 @docusaurus/preset-classic 文档。

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 - 现在默认使用干净 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 扩展名访问。

例如，存在以下 2 个页面

• 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，文档可以在 front matter 中声明 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

Bun

bun run swizzle @docusaurus/theme-classic Footer

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

不要仅仅为了在左侧添加徽标而 swizzle 页脚。徽标在 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',
      },
    },
  },
};

页面

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

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

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

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

v2 中已弃用 CompLibrary，因此您必须编写自己的 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。

Front matter 由 gray-matter 解析。如果您的 front matter 使用特殊字符如 :，您现在需要引用它：title: Part 1: my part1 title → title: "Part 1: my part1 title"。

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

特定语言的代码选项卡

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

Front matter

Docusaurus 博客的 front matter 字段已从 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

Bun

cd website
bun start

您也可以尝试为生产环境构建站点

npm

npm run build

Yarn

yarn build

pnpm

pnpm run build

Bun

bun run build