Docusaurus 3.3
We are happy to announce Docusaurus 3.3.
Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.
We are happy to announce Docusaurus 3.3.
Upgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.
我们很高兴地宣布 Docusaurus 3.2 现已发布。
The upgrade should be easy: as explained in our release process documentation, minor versions respect Semantic Versioning.
We are happy to announce Docusaurus 3.1.
The upgrade should be easy: as explained in our release process documentation, minor versions respect Semantic Versioning.
Today, we are happy to announce Docusaurus 3.0! 🥳
At Meta Open Source, we believe Docusaurus will help you build the best documentation websites with minimal effort, letting you focus on what really matters: writing the content.
This is a new major version of Docusaurus, coming with new exciting features and upgraded dependencies.
In line with the Semantic Versioning principles, this release includes breaking changes we documented thoroughly in the v3 upgrade guide. Breaking changes can be bothersome, but they are necessary to set the ground for a new wave of Docusaurus features we plan to implement.
We initially planned to release more frequent major versions, but Docusaurus v3 has taken longer than expected. Among the breaking changes that we accrued, upgrading to MDX v3 is probably the main challenge to the adoption of this new version. We went the extra mile to make this upgrade as easy as possible, notably by adding compatibility options for MDX v1.
The simplest sites will only need to upgrade a few npm dependencies. For more complex sites, we came up with a few strategies that can help you upgrade more confidently:
According to our release process, Docusaurus v2 has now entered maintenance mode. It will only receive support for major security issues for 3 months, until 31 January 2024. It is recommended to upgrade within that time frame to v3.
This section only gives you a quick glance. All the breaking changes are thoroughly documented in the v3 upgrade guide.
Docusaurus v3 upgraded a few dependencies to new major versions, each coming with its own breaking changes:
A typical package.json
dependency upgrade looks like:
{
"dependencies": {
// upgrade to Docusaurus v3
- "@docusaurus/core": "2.4.3",
- "@docusaurus/preset-classic": "2.4.3",
+ "@docusaurus/core": "3.0.0",
+ "@docusaurus/preset-classic": "3.0.0",
// upgrade to MDX v3
- "@mdx-js/react": "^1.6.22",
+ "@mdx-js/react": "^3.0.0",
// upgrade to prism-react-renderer v2.0+
- "prism-react-renderer": "^1.3.5",
+ "prism-react-renderer": "^2.1.0",
// upgrade to React v18.0+
- "react": "^17.0.2",
- "react-dom": "^17.0.2"
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0"
},
"devDependencies": {
// upgrade Docusaurus dev dependencies to v3
- "@docusaurus/module-type-aliases": "2.4.3",
- "@docusaurus/types": "2.4.3"
+ "@docusaurus/module-type-aliases": "3.0.0",
+ "@docusaurus/types": "3.0.0"
}
"engines": {
// require Node.js 18.0+
- "node": ">=16.14"
+ "node": ">=18.0"
}
}
Apart from MDX v3, most breaking changes coming with those upgraded dependencies have been handled internally for you: most of the time, you shouldn't have to do anything. Outside of dependencies, the only functional breaking changes coming explicitly from the Docusaurus codebase are:
:::warning
admonition, deprecate :::caution
v2.0.0-beta.10
(December 2021)Below is a non-exhaustive list of new useful features coming with this new version. All the features are listed in the Docusaurus v3.0.0 release notes.
Docusaurus v3 upgraded from MDX v1 to MDX v3:
This new MDX version is much better for content writers and plugin authors, and lays the ground for implementing new exciting Markdown features.
The transition from MDX v1 to MDX v3 is the main challenge to the adoption of Docusaurus v3.
Some documents that compiled successfully under Docusaurus v2 might now fail to compile under Docusaurus v3, while others might render differently.
Most breaking changes come from MDX v2, and MDX v3 is a relatively small release. 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.
Don't be intimidated. Most problems are easy to fix and often related to {
and <
characters that you now need to escape. However, depending on the size of your site, you might need to edit many files and feel overwhelmed. For this reason, we provide a command npx docusaurus-mdx-checker
to help you get an estimate of the work to be done, and we recommend to prepare your site in advance.
If you created custom MDX plugins (Remark/Rehype), the AST is slightly different, and you might need to refactor them.
This notably enables us to add a CommonMark mode that should make it easier for existing documentations to adopt Docusaurus. It is currently opt-in and experimental and limited (some Docusaurus features will not work). In Docusaurus v3, all files are still interpreted as MDX, but we plan to interpret .md
files as CommonMark in an upcoming major version, and recommend to use the .mdx
extension for any file using JSX or ES modules.
We also introduced a new way to configure Markdown globally for your site, and plan to add more flexible options later.
export default {
markdown: {
format: 'mdx',
mermaid: true,
preprocessor: ({filePath, fileContent}) => {
return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
},
mdx1Compat: {
comments: true,
admonitions: true,
headingIds: true,
},
},
};
Docusaurus now uses the remark-directive plugin to support admonitions. This also offers you the ability to create your own Remark plugins to extend Markdown with your own custom directives such as :textDirective
, ::leafDirective
or :::containerDirective
.
In #9317, we added support for ES Modules and TypeScript config files, including site config, docs sidebars, plugins and presets.
Here are 2 TypeScript examples, giving you a modern experience with IDE autocompletion:
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
const config: Config = {
title: 'My Site',
favicon: 'img/favicon.ico',
// your site config ...
presets: [
[
'classic',
{
// your preset config ...
} satisfies Preset.Options,
],
],
themeConfig: {
// your theme config ...
} satisfies Preset.ThemeConfig,
};
export default config;
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
docs: ['introduction'],
};
export default sidebars;