This manual migration process should be run after the automated migration prcess, to complete the missing parts, or debug issues in the migration CLI output.
In Docusaurus 2, we use scoped package names:
This provides a clear distinction between Docusaurus' official packages and community maintained packages. In another words, all Docusaurus' official packages are namespaced under
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:
Please use the most recent Docusaurus 2 alpha version, which you can check out here (it's tagged
Meanwhile, CLI commands are renamed to
docusaurus <command> (instead of
"scripts" section of your
package.json should be updated as follows:
A typical Docusaurus 2
package.json may look like this:
Update references to the
In Docusaurus 1, all the build artifacts are located within
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
If you are deploying to GitHub pages, make sure to run
yarn deploy instead of
yarn publish-gh-pages script.
.gitignore in your
website should contain:
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.
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
We recommend moving the
docs folder into the
website folder and that is also the default directory structure in v2. Now 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
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
No actions needed, these configuration fields were not modified.
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
Infima uses 7 shades of each color.
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
|CSS Variable Name||Hex||Adjustment|
Replace the variables in
src/css/custom.css with these new variables.
Site meta info such as assets, SEO, copyright info are now handled by themes. To customize them, use the
themeConfig field in your
In Docusaurus 1, header icon and header links were root fields in
Now, these two fields are both handled by the theme:
Deprecated. Pass it as a blog option to
Deprecated. 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.
editUrl should point to (website) Docusaurus project instead of
Deprecated. Pass it as an option to
@docusaurus/preset-classic docs instead:
The following fields are all deprecated, you may remove from your configuration file.
cleanUrl- Clean URL is used by default now.
defaultVersionShown- Versioning is not ported yet. You'd be unable to migration to Docusaurus 2 if you are using versioning. Stay tuned.
docsSideNavCollapsibleis available at
themeConfig.sidebarCollapsible, and this is turned on by default now.
highlight- We now use Prism instead of highlight.js.
markdownOptions- We use MDX in v2 instead of Remarkable. Your markdown options have to be converted to Remark/Rehype plugins.
markdownPlugins- We use MDX in v2 instead of Remarkable. Your markdown plugins have to be converted to Remark/Rehype plugins.
onPageNav- This is turned on by default now.
separateCss- It can imported in the same manner as
usePrism- We now use Prism instead of highlight.js
We intend to implement many of the deprecated config fields as plugins in future. Help will be appreciated!
In v1, all pages were available with or without the
For example, these 2 pages exist:
true: links would target
false: links would target
In v2, by default, the canonical page is
/installation, and not
If you had
cleanUrl: false in v1, it's possible that people published links to
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
If you want to keep the
.html extension as the canonical url of a page, docs can declare a
slug: installation.html frontmatter.
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
website/core/Footer.js is no longer needed. If you want to modify the default footer provided by Docusaurus, swizzle it:
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
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
In Docusaurus v1, pages received the
siteConfig object as props.
In Docusaurus v2, get the
siteConfig object from
In v2, you have to apply the theme layout around each page. The Layout component takes metadata props (
permalink is important, as it defines the canonical url of your page).
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://facebookincubator.github.io/infima/ to see what styles are available).
You can migrate CommonJS to ES6 imports/exports.
Here's a typical Docusaurus v2 page:
The following code could be helpful for migration of various pages:
This feature is replaced by inline table of content
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
<br> which are valid in HTML would have to be explicitly closed now (
<br/>). All tags in MDX documents have to be valid JSX.
Frontmatter is parsed by gray-matter. If your frontmatter 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.
The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.
authorTwitter have been deprecated. They are only used for generating the profile image of the author which can be done via the
After migration, your folder structure should look like this:
Start the development server and fix any errors:
You can also try to build the site for production: