手动迁移

此手动迁移过程应在自动化迁移过程之后运行，以完成缺失的部分或调试迁移 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 支持Docusaurus 项目开箱即用的部署，如果 docs 目录在 website 中。通常最好将文档放在网站内，以便文档和网站其余代码位于一个 website 目录中。

如果您正在迁移 Docusaurus v1 网站，并且有待处理的文档拉取请求，您可以暂时将 /docs 文件夹保留在其原始位置，以避免产生冲突。

请参阅下面的迁移指南以了解 siteConfig.js 中每个字段。

更新的字段

baseUrl、tagline、title、url、favicon、organizationName、projectName、githubHost、scripts、stylesheets

无需操作，这些配置字段未修改。

colors

已弃用。我们为 Docusaurus 2 编写了一个自定义 CSS 框架，称为Infima，它使用 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 扩展名。

例如，这两个页面存在

• 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 前置 matter。

组件

侧边栏

在以前的版本中，不允许嵌套侧边栏类别，并且侧边栏类别只能包含文档 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 中被有意移除并移到底部。只需在 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。

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。

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

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

特定语言的代码选项卡

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

前置 matter

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

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

部署

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

博客 RSS Feed 现在托管在 /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