手动迁移

此手动迁移过程应在自动化迁移过程之后运行，以完成缺失的部分，或调试迁移 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 版本，您可以在这里查看（使用 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 中的默认目录结构。如果 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

/**
 * 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	#459afa		Fail 🔴
--ifm-color-primary-lighter	#2186f9		Fail 🔴
--ifm-color-primary-light	#1580f9		Fail 🔴
--ifm-color-primary	#0673f0	0	Fail 🔴
--ifm-color-primary-dark	#0568d8		AA 👍
--ifm-color-primary-darker	#0562cc		AA 👍
--ifm-color-primary-darkest	#0451a8		AAA 🏅

请将下方变量替换到 src/css/custom.css 文件中。

/src/css/custom.css

:root {
  --ifm-color-primary: #0673f0;
  --ifm-color-primary-dark: #0568d8;
  --ifm-color-primary-darker: #0562cc;
  --ifm-color-primary-darkest: #0451a8;
  --ifm-color-primary-light: #1580f9;
  --ifm-color-primary-lighter: #2186f9;
  --ifm-color-primary-lightest: #459afa;
}
        

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

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

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

If you want to keep the .html extension as the canonical URL of a page, docs can declare a slug: installation.html front 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

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。

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

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

Here's a typical Docusaurus v2 page:

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;

The following code could be helpful for migration of various pages:

• Index page - Flux (recommended), Docusaurus 2, Hermes
• Help/Support page - 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

Bun

cd website
bun start

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

npm

npm run build

Yarn

yarn build

pnpm

pnpm run build

Bun

bun run build