Version: 3.7.0

手动迁移

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

tip

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

CLI 命令

同时，CLI命令被重命名为docusaurus （而不是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页面，请确保运行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编写了一个名为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中。

tip

目标至少为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: { //... },
    },
    // ...
  },
};

warning

您的 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

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

网址

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

例如，存在以下2个页面：

如果 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
Yarn
pnpm

npm run swizzle @docusaurus/theme-classic Footer

yarn swizzle @docusaurus/theme-classic Footer

pnpm run swizzle @docusaurus/theme-classic Footer

这将复制主题当前使用的组件到您网站根目录下的src/theme/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',
      },
    },
  },
};

页面

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

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

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

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

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。因此，现有文档中可能存在一些需要更新的语法错误。一个常见的例子是自闭合标签，如和，它们在 HTML 中是有效的，但现在必须显式关闭（和）。MDX 文档中的所有标签都必须是有效的 JSX。

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

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

特定语言的代码标签

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

前言

博客的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
Yarn
pnpm

cd website
npm start

cd website
yarn start

cd website
pnpm start

你也可以尝试为生产环境构建网站：

npm
Yarn
pnpm

npm run build

yarn build

pnpm run 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​

特定语言的代码标签​

前言​

部署​

测试你的网站​