docusaurus-v2-to-v3-migration
Use when migrating Docusaurus projects from v2 to v3
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.
| name | docusaurus-v2-to-v3-migration |
|---|---|
| # IMPORTANT | Keep description on ONE line for Claude Code compatibility |
| description | Use 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
- Pre-check: Run
npx docusaurus-mdx-checkerto identify MDX issues - Update deps: Upgrade all @docusaurus packages, React, MDX, prism-react-renderer
- Fix MDX: Escape bare
{<characters, convert GFM autolinks, use code fences - Update config: Replace
@tsconfig/docusauruswith@docusaurus/tsconfig, update Prism imports - Test: Run
npm startthennpm run build
Reference Files
- breaking-changes.md - Complete migration guide with examples