website/blog/releases/3.10/index.mdx
We are happy to announce Docusaurus 3.10.
Upgrading is easy. We follow Semantic Versioning, and minor version updates have no breaking changes, according to our release process.
However, if you opt in for upcoming Docusaurus v4 breaking changes globally with future.v4: true, make sure to review the dedicated section below.
import BrowserWindow from '@site/src/components/BrowserWindow';
The Docusaurus v4 Future Flags let you opt in for upcoming Docusaurus v4 breaking changes incrementally and prepare for Docusaurus v4 ahead of time. You can enable them all at once with future.v4: true.
This release introduces new flags and breaking changes that might break your site if you use future.v4: true and upgrade:
future.v4.siteStorageNamespacing: In Docusaurus v4, localStorage keys will be automatically namespaced by default (theme => theme-<hash>) to prevent key conflicts. This is likely to reset your site's visitor storage unless you migrate it to new key names. See the dedicated Site Storage section below.future.v4.fasterByDefault: Docusaurus Faster is now stable and will be enabled by default in Docusaurus v4. See the dedicated Docusaurus Faster section below.future.v4.mdx1CompatDisabledByDefault: In Docusaurus v4, MDX v1 compatibility options will be disabled by default, and you might have to adjust your docs accordingly. See the dedicated Strict MDX section below.npm supply chain attacks have surged recently. A single compromised maintainer or package can ripple through the ecosystem and affect thousands of downstream users, as seen with the axios compromise.
We’ve taken steps to strengthen our supply chain, and recommend securing your own site with additional measures as well.
We adopted npm Trusted Publishing for stable and canary releases.
Releases are now published through a single publish.yml GitHub Actions workflow using short-lived OIDC tokens. Each release has verifiable provenance, with a transparency log showing how and when it was published.
In #11874, we introduced a new security workflow that runs daily and on every pull request. It scans for suspicious dependency updates affecting our official packages and their transitive dependencies:
preinstall and postinstall lifecycle scripts, using pnpm strictDepBuildsblockExoticSubdepstrustPolicy: no-downgrade:::danger Security Limitations
This security workflow does not protect your site. It is designed to detect serious vulnerabilities affecting the Docusaurus ecosystem as early as possible, so we can react quickly and notify you.
With semver dependency ranges, it's impossible to guarantee a 100% secure supply chain, since any new npm release in our dependency graph can introduce a vulnerability. Ultimately, securing your site is your responsibility. At a minimum, rely on a lockfile and upgrade dependencies deliberately and cautiously.
:::
Read the npm security best practices guide to learn how to secure your site — and npm applications in general — from compromised dependencies.
Each package manager offers different security options. In our experience, pnpm offers the best ones. We won't document all the possibilities, but here's a pnpm config example that should work well with Docusaurus:
minimumReleaseAge: 10080
blockExoticSubdeps: true
strictDepBuilds: true
allowBuilds:
'@swc/core': true
core-js-pure: true
core-js: true
trustPolicy: no-downgrade
trustPolicyExclude:
- '[email protected]'
- '[email protected]'
:::tip Use release cooldowns
When a popular npm package gets compromised, the community usually notices quickly and takes it down. Using a release cooldown is an effective way to reduce risk during the exposure window.
Modern package managers now offer a way to delay npm updates, giving time for security scanners to report vulnerabilities.
# npm v11.10+ - .npmrc
min-release-age=7
# pnpm v10.16+ - pnpm-workspace.yaml
minimumReleaseAge: 10080
# Yarn v4.10+ - .yarnrc.yml
npmMinimalAgeGate: "7d"
# Bun v1.3+ - bunfig.toml
[install]
minimumReleaseAge = 604800
:::
Docusaurus Faster lets you opt in for our modernized build infrastructure. This includes Rspack, SWC, LightningCSS, and other optimizations.
This release improves Docusaurus Faster with a new gitEagerVcs flag and full support for Yarn PnP.
In #11802, we marked Docusaurus Faster as stable. You now need to update your config accordingly:
const config = {
future: {
- experimental_faster: true,
+ faster: true,
},
};
:::info Faster By Default in v4
Docusaurus Faster will be enabled by default in Docusaurus v4, and is already used for all newly initialized v3 sites. It is now part of our v4 future flags (future.v4.fasterByDefault: true) to help our community prepare for Docusaurus v4. If you haven't already, now is a good time to turn it on!
:::
In #11797, we marked the config.storage API as stable. You now need to update your config accordingly:
const config = {
+ storage: {
+ type: 'localStorage',
+ namespace: true,
+ },
- future: {
- experimental_storage: {
- type: 'localStorage',
- namespace: true,
- },
- },
};
:::info Automatic namespacing in v4
Docusaurus v4 will automatically namespace your storage keys to avoid localStorage key conflicts by default, and is now part of our v4 future flags (future.v4.siteStorageNamespacing: true). Instead of using a theme key, it will use theme-<hash>.
These storage key conflicts usually happen when running multiple http://localhost:3000 apps, or when running multiple apps under the same domain (https://example.com/app and https://example.com/docs).
:::
This release introduces new MDX options to encourage stricter usage of native MDX syntax, instead of relying on proprietary Docusaurus syntax on top of MDX.
Historically, Docusaurus compiled your files with MDX v1, which was quite forgiving. Since then, the ecosystem has widely moved to MDX v3, which is stricter. Docusaurus v3.0 introduced markdown.mdx1Compat to help you upgrade incrementally.
In Docusaurus v4, we plan to turn the markdown.mdx1Compat options off by default. This upcoming change is now part of our v4 future flags (future.v4.mdx1CompatDisabledByDefault: true).
We'd like the community to adopt a stricter, native MDX syntax for a few reasons:
We believe that:
.md should be parsed as CommonMark.mdx should be parsed as MDXIn reality, Docusaurus has only ever supported MDX, and we should have used the .mdx extension from the start. Newly initialized sites now use .mdx by default (#11897). We encourage you to rename your existing files to .mdx as well, so that external tools can understand your content is MDX.
:::info About CommonMark support
Although we also have experimental support for CommonMark, it still doesn't have full feature parity with MDX (issue). Once we reach full feature parity, we'll default to markdown.format: 'detect' to ensure that .md files are parsed as CommonMark instead of MDX.
:::
We have historically supported admonitions with titles using the :::type My Title syntax. Although convenient, this is a proprietary Docusaurus syntax.
The Markdown Directive syntax is more generic and reusable. It is not yet standardized, but widely adopted across ecosystems, including through the remark-directive package. We encourage you to migrate your admonitions to the :::type[My Title] syntax:
-:::warning Pay Attention
+:::warning[Pay Attention]
Content
:::
MDX v3 does not support HTML comments <!-- comment -->, but supports JSX comment expressions ``.
If you use HTML comments, we encourage you to migrate to JSX comments. For example, you can truncate blog posts with a JSX comment:
# My Blog Post
-<!-- truncate -->
+
blog post content
Our historical heading IDs syntax {#my-id} is also a proprietary Docusaurus syntax, leading to ecosystem incompatibilities.
In #11755, we introduced a new heading ID syntax based on native MDX comments that we encourage you to adopt:
-## My Heading {#my-id}
+## My Heading
In #11777, we also added an option to our write-heading-ids CLI to emit and migrate to the new syntax:
docusaurus write-heading-ids --syntax mdx-comment --migrate
In #11512, we added a new experimental VCS (Version Control System) API, and implemented built-in performance improvements when reading from the Git history.
Historically, Docusaurus only integrated with Git, reading the commit history to implement features such as:
showLastUpdateAuthor or showLastUpdateTime options<lastmod> value in the sitemap pluginThis new API makes it possible to integrate Docusaurus with other VCS, such as SVN, Mercurial, a CMS or any other external system.
Here's an example implementation using hardcoded data:
export default {
future: {
experimental_vcs: {
initialize: ({siteDir}) => {
// You can initialize and cache VCS data here, if needed
},
getFileCreationInfo: async (filePath: string) => {
return {timestamp: 1490997600000, author: 'Slash'};
},
getFileLastUpdateInfo: async (filePath: string) => {
return {timestamp: 1490997600000, author: 'Slash'};
},
},
},
};
We have also noticed that our historical strategy to read from the Git history can be a significant build performance bottleneck for large Docusaurus sites. Issuing one git log <filepath> call per MDX file doesn't scale well.
To solve this bottleneck, we implemented a strategy that reads the whole Git repository eagerly in a single git log call, leading to significant performance improvements. This strategy is now part of Docusaurus Faster (future.faster.gitEagerVcs: true) and will become the default in Docusaurus v4.
We also provide built-in VCS preset strategies. The available presets are:
git-ad-hoc: the historical strategy based on git log <filename> callsgit-eager: the new Git strategy that reads your whole repository upfronthardcoded: returns a hardcoded value, useful in dev/tests to speed up DXdisabled: returns null for all files, considering them untrackeddefault-v1: the historical default (dynamic, git-ad-hoc in prod, hardcoded in dev)default-v2: the upcoming Docusaurus v4 default (dynamic, git-eager in prod, hardcoded in dev)export default {
future: {
experimental_vcs: 'default-v2',
},
};
:::danger Experimental
The VCS API is experimental and its design may change. If you give it a try, please share feedback on this community discussion.
Although the API may change, we consider the built-in Git Eager strategy stable for simple Git repositories. There may be edge cases with multiple nested Git repositories or submodules.
:::
ur theme translations.pt-BR theme translations.Other notable changes include:
"ignoreDeprecations": "6.0" for now.siteConfig.headTags API now accepts custom HTML elements.<DocCard> component to make it easier to extend/swizzle. It's now easier to assign custom emojis for the docs generated index page.<Tabs> component now uses React context instead of props, making it possible to create custom <TabItem> components."strict: true" by default.., the current directory.[text](./other-page.md)), as the docs and blog plugins already support it.:::note{.my-class #my-id}.create-docusaurus CLI, making it faster to create a new site.$$ to improve docs portability.AGENTS.md file. As a reminder, any AI usage in Docusaurus contributions must be disclosed.Check the 3.10.0 changelog entry for an exhaustive list of changes.