Docusaurus V2 To V3 Migration

Quick Start

{
  "@docusaurus/core": "^3.0.0",
  "@mdx-js/react": "^3.0.0",
  "prism-react-renderer": "^2.1.0",
  "react": "^18.2.0"
}

Core Principles

• •MDX v1 → v3: Main challenge - escape { and < characters or wrap in code blocks
• •Node.js >=18.0: Required for Docusaurus v3
• •React 18: Breaking changes may affect custom components

Migration Steps

1. •Pre-check: Run npx docusaurus-mdx-checker to identify MDX issues
2. •Update deps: Upgrade all @docusaurus packages, React, MDX, prism-react-renderer
3. •Fix MDX: Escape bare { < characters, convert GFM autolinks, use code fences
4. •Update config: Replace @tsconfig/docusaurus with @docusaurus/tsconfig, update Prism imports
5. •Test: Run npm start then npm run build

Reference Files

• •breaking-changes.md - Complete migration guide with examples