手动迁移
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.
Project setup
package.json
Scoped package names
在 Docusaurus 2 中,我们的包名都是有命名空间的:
docusaurus
→@docusaurus/core
这允许我们把 Docusaurus 官方包和社区维护的包明确区分开来。 In another words, all Docusaurus' official packages are namespaced under @docusaurus/
.
Meanwhile, the default doc site functionalities provided by Docusaurus 1 are now provided by @docusaurus/preset-classic
. 所以我们也需要添加这个依赖项:
{
dependencies: {
- "docusaurus": "^1.x.x",
+ "@docusaurus/core": "^2.0.0-beta.0",
+ "@docusaurus/preset-classic": "^2.0.0-beta.0",
}
}
Please use the most recent Docusaurus 2 version, which you can check out here (using the latest
tag).
CLI commands
Meanwhile, CLI commands are renamed to docusaurus <command>
(instead of docusaurus-command
).
The "scripts"
section of your package.json
should be updated as follows:
{
"scripts": {
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy"
// ...
}
}
A typical Docusaurus 2 package.json
may look like this:
{
"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"
]
}
}
Update references to the build
directory
In Docusaurus 1, all the build artifacts are located within website/build/<PROJECT_NAME>
.
In Docusaurus 2, it is now moved to just website/build
. Make sure that you update your deployment configuration to read the generated files from the correct build
directory.
If you are deploying to GitHub pages, make sure to run yarn deploy
instead of yarn publish-gh-pages
script.
.gitignore
The .gitignore
in your website
should contain:
# 依赖项
/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 文件了。 You can modify it to reflect the D2 changes, or copy the default Docusaurus v2 README.
Site configurations
docusaurus.config.js
Rename siteConfig.js
to docusaurus.config.js
.
在 Docusaurus 2 中,我们把每个功能(博客、文档、页面)都模块化成了一个插件。 Presets are bundles of plugins and for backward compatibility we built a @docusaurus/preset-classic
preset which bundles most of the essential plugins present in Docusaurus 1.
Add the following preset configuration to your 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'),
},
// ...
},
],
],
};
We recommend moving the docs
folder into the website
folder and that is also the default directory structure in v2. Vercel supports Docusaurus project deployments out-of-the-box if the docs
directory is within the website
. It is also generally better for the docs to be within the website so that the docs and the rest of the website code are co-located within one website
directory.
If you are migrating your Docusaurus v1 website, and there are pending documentation pull requests, you can temporarily keep the /docs
folder to its original place, to avoid producing conflicts.
Refer to migration guide below for each field in siteConfig.js
.
Updated fields
baseUrl
, tagline
, title
, url
, favicon
, organizationName
, projectName
, githubHost
, scripts
, stylesheets
无需操作,这些配置字段没有变化。
colors
已废弃。 We wrote a custom CSS framework for Docusaurus 2 called Infima which uses CSS variables for theming. 文档还没有完工,完成后我们会在这里更新链接。 To overwrite Infima's CSS variables, create your own CSS file (e.g. ./src/css/custom.css
) and import it globally by passing it as an option to @docusaurus/preset-classic
:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
theme: {
customCss: [require.resolve('./src/css/custom.css')],
},
},
],
],
};
Infima 每种颜色都使用 7 种色度。
/**
* 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);
}
We recommend using ColorBox to find the different shades of colors for your chosen primary color.
Alternatively, use the following tool to generate the different shades for your website and copy the variables into src/css/custom.css
.
主色调最好至少有 WCAG-AA 对比度,以保证可读性。你可以用 Docusaurus 自己的网站来预览你的配色的效果。深色模式下,你可以换一套配色,因为同一种颜色一般不能在浅色和深色模式下都保持足够的可读性。
CSS 变量名称 | 十六进制值 | 颜色调整值 | 对比度评分 |
---|---|---|---|
--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 🏅 |
把 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、版权信息等,现在由主题处理。 To customize them, use the themeConfig
field in your 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
In Docusaurus 1, header icon and header links were root fields in 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 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
module.exports = {
// ...
themeConfig: {
algolia: {
apiKey: '47ecd3b21be71c5822571b9f59e52544',
indexName: 'docusaurus-2',
algoliaOptions: { //... },
},
// ...
},
};
blogSidebarCount
已废弃。 Pass it as a blog option to @docusaurus/preset-classic
instead:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
postsPerPage: 10,
},
// ...
},
],
],
};
cname
已废弃。 Create a CNAME
file in your static
folder instead with your custom domain. Files in the static
folder will be copied into the root of the build
folder during execution of the build command.
customDocsPath
, docsUrl
, editUrl
, enableUpdateBy
, enableUpdateTime
BREAKING: editUrl
should point to (website) Docusaurus project instead of docs
directory.
已废弃。 Pass it as an option to @docusaurus/preset-classic
docs instead:
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
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
// ...
googleAnalytics: {
trackingID: 'UA-141789564-1',
},
},
],
],
};
gaGtag
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
// ...
gtag: {
trackingID: 'UA-141789564-1',
},
},
],
],
};
Removed fields
以下字段都已废弃,你可以从配置文件中移除。
blogSidebarTitle
cleanUrl
- Clean URL is used by default now.defaultVersionShown
- Versioning is not ported yet. 如果你有文档分版,你还不能迁移到 Docusaurus 2。 敬请期待。disableHeaderTitle
disableTitleTagline
docsSideNavCollapsible
is available atdocsPluginOptions.sidebarCollapsible
, and this is turned on by default now.facebookAppId
facebookComments
facebookPixelId
fonts
highlight
- We now use Prism instead of highlight.js.markdownOptions
- We use MDX in v2 instead of Remarkable. 你的 Markdown 选项必须转换为 Remak/Rehype 插件。markdownPlugins
- We use MDX in v2 instead of Remarkable. 你的 Markdown 插件必须转换为 Remak/Rehype 插件。manifest
onPageNav
- This is turned on by default now.separateCss
- It can imported in the same manner ascustom.css
mentioned above.scrollToTop
scrollToTopOptions
translationRecruitingLink
twitter
twitterUsername
useEnglishUrl
users
usePrism
- We now use Prism instead of highlight.jswrapPagesHTML
我们打算在今后把许多废弃的配置字段作为插件实现。 如果你愿意帮忙,我们不胜感激!
Urls
In v1, all pages were available with or without the .html
extension.
例如,这两种页面都存在:
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
.
出于 SEO 原因,并避免链接失效,你应该在你的托管服务提供商上配置服务器端重定向规则。
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.
Components
Sidebar
在之前的版本中,不允许嵌套侧边栏类别,侧边栏类别只能包含文档 ID。 However, v2 allows infinite nested sidebar and we have many types of Sidebar Item other than document.
如果你的侧边栏包含类别类型,你将需要迁移你的侧边栏。 Rename subcategory
to category
and ids
to items
.
{
- type: 'subcategory',
+ type: 'category',
label: 'My Example Subcategory',
+ items: ['doc1'],
- ids: ['doc1']
},
Footer
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.
不要仅仅为了在左侧添加 logo 而 swizzle 页脚组件。 在 v2 版本中,logo 被有意移除并移动到了底部。 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',
},
},
},
};
Pages
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">
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
Content
Replace AUTOGENERATED_TABLE_OF_CONTENTS
This feature is replaced by inline table of content
Update Markdown syntax to be MDX-compatible
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.
Language-specific code tabs
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.
Deployment
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.
Test your site
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:
- npm
- Yarn
- pnpm
cd website
npm start
cd website
yarn start
cd website
pnpm start
You can also try to build the site for production:
- npm
- Yarn
- pnpm
npm run build
yarn build
pnpm run build