Docusaurus V4 - Umbrella issue

This is a meta issue to gather information about the upcoming Docusaurus v4 release.
This comment will be updated regularly as we progress toward v4.

If you have opinions on breaking changes and dependency upgrades we should focus on, please let us know.

Apart from that, I'd like to keep the release relatively small, to make it easy to adopt, and to not delay it more than needed.

Top Priority changes

These are the changes we really want for v4. The list is already quite long, so I'm likely to migrate some items to optional changes.

Dependency upgrades:

Behaviors:

Also: handle all the // TODO Docusaurus v4 comments in code

Optional changes

These are the changes we'd like to have for v4, but if they are too complicated, difficult to implement, or too disruptive for users, we may postpone them to another major version.

Deprecate algolia.themeConfig in favor of plugin/preset options?
v4.0 milestone contains various fixes/upgrades requiring breaking changes or version upgrades
Babel 8 for Docusaurus Slower?
Deprecate getSwizzleComponentList in favor of getSwizzleConfig
Truncate blog markdown loader with AST/remark instead of String split regexp
.md parsed as CommonMark by default?
Internalize and shrink down Infima
Chokidar v4? or migrate to Parcel watcher like many others?
@rspack/plugin-react-refresh
Deprecate configureWebpack(...args) in favor of configureBundler({params})

Rejected changes

react-helmet-async v3+ (v3.0.0 — React 19 support, TypeScript cleanup, switch to pnpm staylor/react-helmet-async#260): I tried updating, and it didn't work well. For React v19 this lib is a quite useless pass-through. For that reason, we'll stay on my fork that added v19 support. There are alternatives to consider in Support for react 19 staylor/react-helmet-async#239 (unjs/head and birdofpreyru/react-helmet), but no need to upgrade immediately.
Babel 8 (break: upgrade to Babel v8 #12408): PR has been closed for the reasons mentioned at the top. Not really needed right now, and would lead to a duplicate Babel7/8 version anyway.

Curious on the gray-matter replacement, what is the motivation there? No opinions on removing or replacing it, just curious!

Something I know that has been touted a lot is tailwind support. I've managed to get it running in my project but it doesn't feel that great. Infima seems to have lost development effort, commits from the last few years are dependabot PRs or minor improvements. Even the home page says it is being developed alongside v2 of docusaurus so it feels quite stale. Moving it into docusaurus feels like a good step and would remove confusion and give developers a clearer path to customisation.

gray-matter is mostly unmaintained and also has some weird behaviors, like a confusing internal front matter caching system that makes it unsafe to modify the object it returns. I'm pretty sure I've seen newer front matter libraries that are maintained, faster, and safer to use.

Infima is not developed outside of Docusaurus. I'd like to re-integrate it into Docusaurus theme classic to reduce maintenance friction (added it to the list). That would actually help us port our theme to Tailwind.

.md parsed as CommonMark by default?

Hi, will there be an option to configure how .md files are parsed? Currently .md files are parsed as MDX, and my editor has excellent syntax highlighting and formatting support for Markdown files but no support for MDX files, so I exclusively use .md files (I haven't found a suitable MDX VS Code extension yet). What's the end goal of this parsing behavior change? Will parsing options be available, or will they eventually be phased out until only CommonMark parsing remains? This is important for my future documentation work. Thanks!

Would love to see Infima merged into Docusaurus in v4. This would definitely reduce confusion and make it easier for users to customize things.

Hi, will there be an option to configure how .md files are parsed? Currently .md files are parsed as MDX, and my editor has excellent syntax highlighting and formatting support for Markdown files but no support for MDX files, so I exclusively use .md files (I haven't found a suitable MDX VS Code extension yet). What's the end goal of this parsing behavior change? Will parsing options be available, or will they eventually be phased out until only CommonMark parsing remains? This is important for my future documentation work. Thanks!

We already have options to parse md as CommonMark, it's just not have full feature parity with MDX. Note, in both cases, things are parsed with MDX, which has a format: 'md' mode.

https://docusaurus.io/docs/markdown-features#mdx-vs-commonmark

We'd like to keep supporting both modes and ensure both have feature parity. For example, in format: md mode it's not possible to use Tabs currently because our API relies on JSX. In the future, we could bring this feature parity for tabs by exposing an html-like syntax (<tabs> instead of <Tabs>) or a directive syntax (:::tabs). Hope this makes sense.

The ajv ReDoS-vuln that popped up yesterday made me notice that @docusaurus/bundler depend on the deprecated and archived https://github.com/webpack-contrib/file-loader. Is moving to RSPack removing this slightly problematic old dependency chain?

❯ pnpm why ajv
ajv@6.12.6
├─┬ ajv-keywords@3.5.2
│ └─┬ schema-utils@3.3.0
│   ├─┬ file-loader@6.2.0
│   │ ├─┬ @docusaurus/bundler@3.9.2
|   | | ...
│   │ ├─┬ @docusaurus/mdx-loader@3.9.2
|   | | ...
│   │ ├─┬ @docusaurus/utils@3.9.2
|   | | ...
│   │ └─┬ url-loader@4.1.1
|   |   ...
│   ├─┬ null-loader@4.0.1
│   │ └── @docusaurus/bundler@3.9.2 [deduped]
│   └── url-loader@4.1.1 [deduped]
└── schema-utils@3.3.0 [deduped]

One of the items on the v4 milestone is eslint v9 compatibility for the docusaurus eslint plugin. eslint v10 has since been released, so this might need to be re-looked at.

Hello 👋

I was wondering if we could consider adding React Compiler support for v4? The React team actually suggests compiling libraries, as mentioned in their documentation.

My initial thought is to update the docusaurus-babel preset (around here) to include the compiler plugin. For a safe migration, we could optionally enable it using compilationMode: 'annotation'.

Please let me know if this makes sense. I apologize if this isn't the right approach or place for this, but I would be more than happy to submit a PR if you're open to the idea!

Thank you!

TLDR: not the right time to accept React Compiler PRs.

However, our codebase already respects the React Compiler eslint rules: #10969

It doesn't seem like the right timing to work on a React Compiler integration, considering it only integrates nicely with Babel, and we want to enable Docusaurus Faster (Rspack/SWC) by default for v4. Although technically possible (see what Next.js is doing), it's challenging and probably better to wait.

The React team is porting the React Compiler to Rust, which would make it possible to integrate with SWC in a better, more performant way in the future: oxc-project/oxc#10048

Note that if your site uses Babel (not opting in for Docusaurus Faster) and want to use the React Compiler, you can already add the plugin to your site's Babel config, and it should normally work. However, this will only optimize your site's source code, which is generally composed of MDX more than JSX/TSX, so there's probably not much to optimize there.

IMHO, most of the code to optimize is in the official theme packages. We plan to optimize that code later, too, once SWC can support the React Compiler. But there's something to consider: docusaurus swizzle can eject theme files to your site's source, and the emitted code must remain readable, easy to edit manually. So, even if we pre-compile our lib, we still want our "source" to be sufficiently optimized so that if a site ejects it and is not using the compiler, that code remains fast. We don't want "ejecting" to make your site slower.

TLDR: not the right time to accept React Compiler PRs.

However, our codebase already respects the React Compiler eslint rules: #10969

It doesn't seem like the right timing to work on a React Compiler integration, considering it only integrates nicely with Babel, and we want to enable Docusaurus Faster (Rspack/SWC) by default for v4. Although technically possible (see what Next.js is doing), it's challenging and probably better to wait.

The React team is porting the React Compiler to Rust, which would make it possible to integrate with SWC in a better, more performant way in the future: oxc-project/oxc#10048

Note that if your site uses Babel (not opting in for Docusaurus Faster) and want to use the React Compiler, you can already add the plugin to your site's Babel config, and it should normally work. However, this will only optimize your site's source code, which is generally composed of MDX more than JSX/TSX, so there's probably not much to optimize there.

IMHO, most of the code to optimize is in the official theme packages. We plan to optimize that code later, too, once SWC can support the React Compiler. But there's something to consider: docusaurus swizzle can eject theme files to your site's source, and the emitted code must remain readable, easy to edit manually. So, even if we pre-compile our lib, we still want our "source" to be sufficiently optimized so that if a site ejects it and is not using the compiler, that code remains fast. We don't want "ejecting" to make your site slower.

Thanks for the explanation, that makes sense.

Would you be open to me taking a stab at a React Router v7 migration? I'd like to "just try" and see what the feasibility looks like, but I wanted to check if you'd be interested in that before I start tinkering with it.

Would you be open to me taking a stab at a React Router v7 migration? I'd like to "just try" and see what the feasibility looks like, but I wanted to check if you'd be interested in that before I start tinkering with it.

Thanks for the proposal, but I'd rather not. This is one of the things that is the most likely to produce subtle but annoying breaking changes to our community and is the first thing I plan to work on for Docusaurus v4. I'm also directly in touch with the React Router team and we'll likely upgrade to React Router v8. We already had a POC of upgrading to v6 here: #6037

On replacing gray-matter, here's a fork maintained by 11ty: https://github.com/11ty/gray-matter

hello, dont know if this is right place to ask but any estimate when v4 will be released?

Hello 👋,

Since planning for the Docusaurus v4 roadmap is underway, I wanted to suggest exploring support for the browser-native Speculation Rules API for page prefetching and client-side prerendering.

Several other modern static site frameworks have started adopting this mechanism. It provides a highly efficient, browser-optimized way to handle speculative loading while naturally respecting user preferences (like battery-saver or data-saver modes). This could be a great performance addition for the v4 release.

I would love to help implement or prototype this feature, but I would appreciate a quick pointer to kick-start my contribution. Could anyone guide me on:

Where in the codebase the main prefetch/preload utilities (such as window.docusaurus.prefetch or the <Link> prefetch logic) are defined?
Any key architectural boundaries or constraints I should keep in mind for this?

Any brief guidance to point me in the right direction would be highly appreciated!

@sanjaiyan-dev

@sanjaiyan-dev we are an SPA framework and already implement prefetching using JavaScript with more granular control. Adding these wouldn't improve anything and would actually produce useless work for browsers.

Using native speculation rules wouldn't be very helpful because:

we already preload the link's target page javascript
we navigate using history.pushState() and render the next page client-side: we do not need to preload the target HTML page

Speculation rules are only supported for full page navigations managed by the browser, and not for Single Page Apps (SPA) or app shell pages.

https://developer.chrome.com/docs/web-platform/prerender-pages#speculation_rules_and_spas

The only situation where this could make sense is if we support a mode to build Docusaurus as an MPA. But we don't support that mode yet. Related issue: #3030

@sanjaiyan-dev we are an SPA framework and already implement prefetching using JavaScript with more granular control. Adding these wouldn't improve anything and would actually produce useless work for browsers.

Using native speculation rules wouldn't be very helpful because:

we already preload the link's target page javascript

we navigate using history.pushState() and render the next page client-side: we do not need to preload the target HTML page

Speculation rules are only supported for full page navigations managed by the browser, and not for Single Page Apps (SPA) or app shell pages.

https://developer.chrome.com/docs/web-platform/prerender-pages#speculation_rules_and_spas

The only situation where this could make sense is if we support a mode to build Docusaurus as an MPA. But we don't support that mode yet. Related issue: #3030

Thank you for the explanation and the link. I apologize for the oversight regarding SPA limitations with speculation rules, and I appreciate you taking the time to clarify how the framework handles prefetching.

I think it is time to move forward to TypeScript 7, especially for performance.

We already have a PR for that, currently blocked but it should be ready to merge once v7.1 is out or if we adopt oxlint instead of eslint.

#12264

Will this release include or pave the way for any of the AEO-related features, e.g. 'Copy to Markdown', 'Open with Claude' and such? We are considering using this 3rd party plugin but would be interesting to have such features in the mainline

This feature doesn't require breaking change and can be built in userland as many plugins demonsteate, so we are more likely to introduce an official solution in 4.x but not 4.0

I'd like to suggest considering native SSG-MD / llms.txt support for v4 (inspired by Rspress's SSG-MD). This renders .md files alongside HTML so docs are AI/LLM-friendly out of the box.

I’d be happy to help build this! Since I'm unfamiliar with Docusaurus internals, could someone kindly give a brief pointer on the best approach (e.g., core plugin vs. build-step integration)?

Navigation Menu

Repository navigation

Docusaurus V4 - Umbrella issue #11719

Top Priority changes

Optional changes

Rejected changes

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Docusaurus V4 - Umbrella issue #11719

Description

Top Priority changes

Optional changes

Rejected changes

Activity

omonk commented on Feb 9, 2026

slorber commented on Feb 9, 2026

eMUQI commented on Feb 11, 2026

danielclow commented on Feb 11, 2026

slorber commented on Feb 12, 2026

StefanWallin commented on Feb 18, 2026

rainecheck commented on Feb 18, 2026

sanjaiyan-dev commented on Mar 28, 2026

slorber commented on Mar 30, 2026

sanjaiyan-dev commented on Apr 6, 2026

slorber commented on Apr 7, 2026

onyb commented on Jun 16, 2026

soymadip commented on Jun 19, 2026

sanjaiyan-dev commented on Jun 19, 2026

slorber commented on Jun 19, 2026

sanjaiyan-dev commented on Jun 24, 2026

absgrlyp commented on Jul 21, 2026

slorber commented on Jul 21, 2026

lucasbrbz commented on Jul 21, 2026

slorber commented on Jul 22, 2026

sanjaiyan-dev commented on Aug 4, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions