Manual migration
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β
In Docusaurus 2, we use scoped package names:
docusaurus
β@docusaurus/core
This provides a clear distinction between Docusaurus' official packages and community maintained packages. 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
. Therefore, we need to add this dependency as well:
{
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:
# 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
β
The D1 website may have an existing README file. 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
.
In Docusaurus 2, we split each functionality (blog, docs, pages) into plugins for modularity. 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
β
No actions needed, these configuration fields were not modified.
colors
β
Deprecated. We wrote a custom CSS framework for Docusaurus 2 called Infima which uses CSS variables for theming. The docs are not quite ready yet and we will update here when it is. 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 uses 7 shades of each color.
/**
* 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.
Alteratively, use the following tool to generate the different shades for your website and copy the variables into 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
β
Site meta info such as assets, SEO, copyright info are now handled by themes. 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: "Getting Started" },
{ page: "help", label: "Help" },
{ href: "https://github.com/", label: "GitHub" },
{ blog: true, label: "Blog" },
],
Now, these two fields are both handled by the theme:
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: { //... },
},
// ...
},
};
Your Algolia DocSearch v1 config (found here) should be updated for Docusaurus v2 (example).
You can contact the DocSearch team (@shortcuts, @s-pace) for support. They can update it for you and trigger a recrawl of your site to restore the search (otherwise you will have to wait up to 24h for the next scheduled crawl)
blogSidebarCount
β
Deprecated. Pass it as a blog option to @docusaurus/preset-classic
instead:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
postsPerPage: 10,
},
// ...
},
],
],
};