# Docusaurus V2 To V3 Migration

> Use when migrating Docusaurus projects from v2 to v3

- Skill: `majiayu000/docusaurus-v2-to-v3-migration` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/docusaurus-v2-to-v3-migration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/docusaurus-v2-to-v3-migration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/docusaurus-v2-to-v3-migration

---


# Docusaurus V2 To V3 Migration

## Quick Start

```json
{
  "@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](references/breaking-changes.md) - Complete migration guide with examples

<!--
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
-->