Docusaurus v3 is now in beta and the official release is around the corner. This is the perfect time to start preparing your site for this new major version.
Docusaurus v3 comes with a few breaking changes, many of which can be handled today under Docusaurus v2. Preparing your site ahead of time can be done incrementally, and will make it easier to upgrade to v3.
The most important Docusaurus v3 breaking change is the upgrade to MDX v2, which will compile your Markdown content more strictly and with subtle differences.
This article will mostly focus on how to prepare your content for this new MDX version, and will also list a few other breaking changes that you can handle today.
This article mentions most Docusaurus v3 breaking changes, but is not exhaustive. Read the v3.0.0-beta.0 release notes for an exhaustive list.
There's a lot of content in this blog post, but many Docusaurus v2 sites can upgrade with very few changes.
If your site is relatively small, with only a few customizations, you can probably upgrade to Docusaurus v3 immediately.
Preparatory work
Before preparing for the Docusaurus v3 upgrade, we recommend upgrading to the latest Docusaurus v2 version.
Depending on the complexity of your site, it may be a good idea to adopt the visual regression testing workflow that we recently presented. It could help you catch unexpected visual side effects occurring during the Docusaurus v3 upgrade.
We also recommend using the .mdx
extension whenever you use JSX, import
, or export
(i.e. MDX features) inside a Markdown file. It is semantically more correct and improves compatibility with external tools (IDEs, formatters, linters, etc.). In future versions of Docusaurus, .md
files will be parsed as standard CommonMark, which does not support these features. In Docusaurus v3, .md
files keep being compiled as MDX files, but it will be possible to opt-in for CommonMark.
Preparing content for MDX v2
MDX is a major dependency of Docusaurus responsible for compiling your .md
and .mdx
files to React components.
MDX v2 is much better, but also comes with changes that probably require you to refactor your content a bit. MDX v2 is stricter, and some components that compiled fine under v1 might now fail to compile under v2, most likely because of {
and <
characters.
Upgrading MDX comes with all the breaking changes documented on the MDX v2 release blog post. The MDX v2 migration guide has a section on how to update MDX files that will be particularly relevant to us. Also make sure to read the Troubleshooting MDX page that can help you interpret common MDX error messages.
Make sure to also read our updated MDX and React documentation page.
We have a dedicated MDX v2 - Upgrade Support discussion.
Using the MDX playground
The MDX playground is your new best friend. It permits to understand how your content is compiled to React components, and troubleshoot compilation or rendering issues in isolation.
Each MDX version comes with its own playground:
Configuring MDX v2 playground options for Docusaurus
To obtain a compilation behavior similar to what Docusaurus v2 uses, please turn on these options on the MDX v2 playground:
- Use
MDX
- Use
remark-gfm
- Use
remark-directive
Using the two MDX playgrounds side-by-side, you will soon notice that some content is compiled differently or fails to compile in v2.
The goal will be to refactor your problematic content so that it works fine with both versions of MDX. This way, when you upgrade to Docusaurus v3, this content will already work out-of-the-box.
Using the MDX checker CLI
We provide a docusaurus-mdx-checker CLI that permits to easily spot problematic content. Run this command today on your Docusaurus v2 site to obtain a list of files that will fail to compile under MDX v2.
npx docusaurus-mdx-checker
For each compilation issue, the CLI will log the file path and a line number to look at.
Use this CLI to estimate of how much work will be required to make your content compatible with MDX v2.
This CLI is a best effort, and will only report compilation errors.
It will not report subtle compilation changes that do not produce errors but can affect how your content is displayed. To catch these problems, we recommend using visual regression tests.
Common MDX problems
We upgraded a few Docusaurus sites to Docusaurus v3 and MDX v2:
These upgrades permitted us to aggregate the most common content problems, and document how to best handle them.