Which strategy should I use for Docusaurus 2 to 3?

Documentation teams need a current migration plan from Docusaurus 2 to 3, especially where MDX plugins, custom remark transforms, or older CI runtimes are involved.

Use a two-phase migration unless your CI is already on Node 18+ and MDX/plugins pass audit cleanly; go straight to Docusaurus 3.9.x only when customizations are light.

Blockers

Who this is for

Candidates

Upgrade directly to Docusaurus 3.9.x after an MDX and plugin audit

As of 2026-04-03, the official Docusaurus docs site shows stable version 3.9.2 and still exposes a 2.x docs line. The official v3 migration guide says Docusaurus 3 requires Node.js 18.0+, React 18.0+, MDX 3.0+, and TypeScript 5.1+. The main breaking change is the MDX v1 to MDX v3 jump, and the guide recommends running `npx docusaurus-mdx-checker` plus visual regression tests before the cutover. This is the right target when your third-party plugins and swizzled theme components are already compatible with v3.

When to choose

Use this when your site mostly stays within official themes and plugins, or when your customizations are limited enough to retest in one migration window. It is the fastest path once your CI runtime is already on Node 18+ and your MDX content compiles cleanly under the checker.

Tradeoffs

You get onto the current stable major quickly and align with the current dependency stack, but you absorb MDX, React, TypeScript, and plugin compatibility changes at once.

Cautions

Official Remark/Rehype/Unified packages used in the MDX ecosystem are ESM-only, so CommonJS `require()` plugin loading breaks. Swizzled docs theme components may need to be deleted, re-swizzled, and reapplied. If you rely on math plugins, the migration guide specifically calls for `remark-math` 6 and `rehype-katex` 7 with Docusaurus 3.

Sources

Use a two-phase migration: harden Docusaurus 2 first, then switch to v3

The official preparation guide says many Docusaurus 3 breaking changes can be handled incrementally while still on Docusaurus 2, and recommends upgrading to the latest Docusaurus 2 version before the major jump. As of 2026-04-03, this is the safer route for teams with custom remark/rehype transforms, lots of legacy `.md` files using MDX syntax, or CI images still pinned to Node 16. The same official guidance recommends moving your Docusaurus 2 site to Node 18 before the v3 upgrade and using the MDX checker to find content that will fail under MDX 3. This turns the migration into a content-and-build hardening project first, and a package bump second.

When to choose

Use this when custom MDX plugins, CommonJS config loading, or old build images are the main blockers. It is the better choice when you need to separate content cleanup, Node runtime changes, and final dependency upgrades into smaller reviewable steps.

Tradeoffs

This reduces migration risk and makes failures easier to isolate, but it extends the calendar time and leaves you temporarily maintaining pre-v3 code longer.

Cautions

As of 2026-04-03, Node.js 16 end-of-life has already occurred; the Node project moved its EOL date to September 11, 2023, and Docusaurus v3 requires Node 18+, so older CI/CD runners are a hard blocker. The preparation guide also warns that `.md` files with JSX, `import`, or `export` should be treated as `.mdx`, because future Docusaurus versions may parse `.md` as CommonMark instead.

Sources

Facts updated: 2026-04-03
Published: 2026-04-03

Related questions

Try with your AI agent

$ npm install -g pocketlantern
$ pocketlantern init
# Restart Claude Code, Cursor, or your MCP client, then ask:
# "Which strategy should I use for Docusaurus 2 to 3?"
Missing something? Request coverage