手动迁移
This manual migration process should be run after the automated migration process, to complete the missing parts, or debug issues in the migration CLI output.
项目设置
package.json
包命名空间
在 Docusaurus 2 中,我们的包名都是有命名空间的:
docusaurus
→@docusaurus/core
这允许我们把 Docusaurus 官方包和社区维护的包明确区分开来。 换句话说,所有 Docusaurus 的官方包都会在 @docusaurus/
命名空间下。
与此同时,Docusaurus 1 提供的默认文档站点功能现在由 @docusaurus/preset-classic
提供。 所以我们也需要添加这个依赖项:
{
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"
部分应该更新为如下内容:
{
"scripts": {
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy"
// ...
}
}
典型的 Docusaurus 2 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 pages,请务必运行 yarn deploy
而不是 yarn publish-gh-pages
脚本。
.gitignore
你的 website
文件夹的 .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
中添加如下预设配置:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// 相对于站点目录的文档目录路径。
path: '../docs',
// 相对于站点目录的侧边栏文件。
sidebarPath: require.resolve('./sidebars.json'),
},
// ...
},
],
],
};
我们建议把 docs
目录移进 website
目录。v2 的默认文件结构也是这样的。 Vercel 开箱即用地支持 Docusaurus 项目部署,但前提是 docs
目录在 website
里面。 一般来说,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
的选项全局导入:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
},
],
],
};
Infima 每种颜色都使用 7 种色度。
/**
* 你可以在这里覆盖默认的 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.
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.
: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
字段:
module.exports = {
// ...
themeConfig: {
footer: {
logo: {
alt: 'Meta 开源图标',
src: '/img/meta_oss_logo.png',
href: 'https://opensource.facebook.com/',
},
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // 你也可以用自己的 HTML。
},
image: 'img/docusaurus.png',
// ...
},
};
headerIcon
, headerLinks
在 Docusaurus 1 中,导航栏图标和导航栏链接是 siteConfig
中的根字段:
headerIcon: 'img/docusaurus.svg',
headerLinks: [
{ doc: "doc1", label: "上手" },
{ page: "help", label: "帮助" },
{ href: "https://github.com/", label: "GitHub" },
{ blog: true, label: "博客" },
],
现在,这些字段都是由主题处理的:
module.exports = {
// ...
themeConfig: {
navbar: {
title: 'Docusaurus',
logo: {
alt: 'Docusaurus 图标',
src: 'img/docusaurus.svg',
},
items: [
{to: 'docs/doc1', label: '上手', position: 'left'},
{to: 'help', label: '帮助', position: 'left'},
{
href: 'https://github.com/',
label: 'GitHub',
position: 'right',
},
{to: 'blog', label: '博客', position: 'left'},
],
},
// ...
},
};
algolia
module.exports = {
// ...
themeConfig: {
algolia: {
apiKey: '47ecd3b21be71c5822571b9f59e52544',
indexName: 'docusaurus-2',
algoliaOptions: { //... },
},
// ...
},
};
blogSidebarCount
已废弃。 这些字段现在是 @docusaurus/preset-classic
的 blog 选项:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
postsPerPage: 10,
},
// ...
},
],
],
};
cname
已废弃。 你可以在 static
文件夹中新建一个 CNAME
文件,然后填写你的自定义域名。 static
文件夹中的文件会在执行构建命令时被复制到 build
文件夹的根部。
customDocsPath
, docsUrl
, editUrl
, enableUpdateBy
, enableUpdateTime
重要变更:editUrl
应该指向 Docusaurus 项目(website 目录)而不是 docs
目录。
已废弃。 这些字段现在是 @docusaurus/preset-classic
的 docs 选项:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
// 等价于 `customDocsPath`。
path: 'docs',
// 等价于 `editUrl` 但应该指向 `website` 目录而不是 `website/docs`。
editUrl: 'https://github.com/facebook/docusaurus/edit/main/website',
// 等价于 `docsUrl`。
routeBasePath: 'docs',
// 传递给 MDX 的 Remark 和 Rehype 插件。 替代了 `markdownOptions` 和 `markdownPlugins`。
remarkPlugins: [],
rehypePlugins: [],
// 等价于 `enableUpdateBy`。
showLastUpdateAuthor: true,
// 等价于 `enableUpdateTime`。
showLastUpdateTime: true,
},
// ...
},
],
],
};
gaTrackingId
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
// ...
googleAnalytics: {
trackingID: 'UA-141789564-1',
},
},
],
],
};
gaGtag
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
- 我们在 v2 中使用 MDX 而不是 Remarkable。 你的 Markdown 选项必须转换为 Remak/Rehype 插件。markdownPlugins
- 我们在 v2 中使用 MDX 而不是 Remarkable。 你的 Markdown 插件必须转换为 Remak/Rehype 插件。manifest
onPageNav
- 现在默认启用。separateCss
- 可以用类似上文提到的custom.css
的方法导入。scrollToTop
scrollToTopOptions
translationRecruitingLink
twitter
twitterUsername
useEnglishUrl
users
usePrism
- 我们现在使用 Prism 而不是 highlight.jswrapPagesHTML
我们打算在今后把许多废弃的配置字段作为插件实现。 如果你愿意帮忙,我们不胜感激!
链接
In v1, all pages were available with or without the .html
extension.
For example, these 2 pages exist:
If cleanUrl
was:
true
: links would target/installation
false
: links would target/installation.html
In v2, by default, the canonical page is /installation
, and not /installation.html
.
If you had cleanUrl: false
in v1, it's possible that people published links to /installation.html
.
For SEO reasons, and avoiding breaking links, you should configure server-side redirect rules on your hosting provider.
As an escape hatch, you could use @docusaurus/plugin-client-redirects to create client-side redirects from /installation.html
to /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.
组件
侧边栏
In previous version, nested sidebar category is not allowed and sidebar category can only contain doc ID. However, v2 allows infinite nested sidebar and we have many types of Sidebar Item other than document.
You'll have to migrate your sidebar if it contains category type. Rename subcategory
to category
and ids
to items
.
{
- type: 'subcategory',
+ type: 'category',
label: 'My Example Subcategory',
+ items: ['doc1'],
- ids: ['doc1']
},
页脚
website/core/Footer.js
is no longer needed. If you want to modify the default footer provided by Docusaurus, swizzle it:
- npm
- Yarn
- pnpm
npm run swizzle @docusaurus/theme-classic Footer
yarn swizzle @docusaurus/theme-classic Footer
pnpm run swizzle @docusaurus/theme-classic Footer
This will copy the current <Footer />
component used by the theme to a src/theme/Footer
directory under the root of your site, you may then edit this component for customization.
Do not swizzle the Footer just to add the logo on the left. The logo is intentionally removed in v2 and moved to the bottom. Just configure the footer in docusaurus.config.js
with themeConfig.footer
:
module.exports = {
themeConfig: {
footer: {
logo: {
alt: 'Meta Open Source Logo',
src: '/img/meta_oss_logo.png',
href: 'https://opensource.facebook.com',
},
},
},
};
页面
Please refer to creating pages to learn how Docusaurus 2 pages work. After reading that, notice that you have to move pages/en
files in v1 to src/pages
instead.
In Docusaurus v1, pages received the siteConfig
object as props.
In Docusaurus v2, get the siteConfig
object from useDocusaurusContext
instead.
In v2, you have to apply the theme layout around each page. The Layout component takes metadata props.
CompLibrary
is deprecated in v2, so you have to write your own React component or use Infima styles (Docs will be available soon, sorry about that! In the meanwhile, inspect the V2 website or view https://infima.dev/ to see what styles are available).
You can migrate CommonJS to ES6 imports/exports.
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">
开始上手
</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
This feature is replaced by inline table of content
更新 Markdown 语法为 MDX 兼容语法
In Docusaurus 2, the Markdown syntax has been changed to MDX. Hence there might be some broken syntax in the existing docs which you would have to update. A common example is self-closing tags like <img>
and <br>
which are valid in HTML would have to be explicitly closed now ( <img/>
and <br/>
). All tags in MDX documents have to be valid JSX.
Front matter is parsed by gray-matter. If your front matter use special characters like :
, you now need to quote it: title: Part 1: my part1 title
→ title: "Part 1: my part1 title"
.
Tips: You might want to use some online tools like HTML to JSX to make the migration easier.
多语言代码选项
Refer to the multi-language support code blocks section.
Front matter
The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.
The fields authorFBID
and authorTwitter
have been deprecated. They are only used for generating the profile image of the author which can be done via the authors
field.
部署
The CNAME
file used by GitHub Pages is not generated anymore, so be sure you have created it in /static/CNAME
if you use a custom domain.
The blog RSS feed is now hosted at /blog/rss.xml
instead of /blog/feed.xml
. You may want to configure server-side redirects so that users' subscriptions keep working.
测试网站
After migration, your folder structure should look like this:
my-project
├── docs
└── website
├── blog
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ └── index.js
├── package.json
├── sidebars.json
├── .gitignore
├── docusaurus.config.js
└── static
Start the development server and fix any errors:
cd website
yarn start
You can also try to build the site for production:
yarn build