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

<!-- PROGRESSIVE DISCLOSURE GUIDELINES: - Keep this file ~50 lines total (max ~150 lines) - Use 1-2 code blocks only (recommend 1) - Keep description <200 chars for Level 1 efficiency - Move detailed docs to references/ for Level 3 loading - This is Level 2 - quick reference ONLY, not a manual LLM WORKFLOW (when editing this file): 1. Write/edit SKILL.md 2. Format (if formatter available) 3. Run: claude-skills-cli validate <path> 4. If multi-line description warning: run claude-skills-cli doctor <path> 5. Validate again to confirm -->