docusaurus-v2-to-v3-migration

codatio's avatarfrom codatio

Use when migrating Docusaurus projects from v2 to v3

⭐18stars🔀41forks📁View on GitHub🕐Updated Jan 9, 2026⬇️3downloads

When & Why to Use This Skill

This Claude skill automates the migration process of Docusaurus projects from version 2 to 3. It provides a structured workflow to handle breaking changes, including MDX v3 syntax adjustments, dependency upgrades for React 18 and Node.js 18+, and configuration updates, ensuring a smooth transition to the latest documentation framework features.

Use Cases

  • Upgrading legacy Docusaurus v2 documentation sites to v3 to access improved performance and new features.
  • Automating the detection and fixing of MDX v3 breaking changes, such as escaping special characters like '{' and '<' in content files.
  • Streamlining dependency management by identifying and updating core packages like @docusaurus/core, React, and Prism-react-renderer to compatible versions.
namedocusaurus-v2-to-v3-migration
# IMPORTANTKeep description on ONE line for Claude Code compatibility
descriptionUse when migrating Docusaurus projects from v2 to v3

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