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-checker to 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/docusaurus with @docusaurus/tsconfig, update Prism imports
Test: Run npm start then npm run build
Reference Files
breaking-changes.md - Complete migration guide with examples
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: docusaurus-v2-to-v3-migration3description: Use when migrating Docusaurus projects from v2 to v34---56# Docusaurus V2 To V3 Migration78## Quick Start910```json11{12 "@docusaurus/core": "^3.0.0",13 "@mdx-js/react": "^3.0.0",14 "prism-react-renderer": "^2.1.0",15 "react": "^18.2.0"16}17```1819## Core Principles2021- **MDX v1 → v3**: Main challenge - escape `{` and `<` characters or wrap in code blocks22- **Node.js >=18.0**: Required for Docusaurus v323- **React 18**: Breaking changes may affect custom components2425## Migration Steps26271. **Pre-check**: Run `npx docusaurus-mdx-checker` to identify MDX issues282. **Update deps**: Upgrade all @docusaurus packages, React, MDX, prism-react-renderer293. **Fix MDX**: Escape bare `{` `<` characters, convert GFM autolinks, use code fences304. **Update config**: Replace `@tsconfig/docusaurus` with `@docusaurus/tsconfig`, update Prism imports315. **Test**: Run `npm start` then `npm run build`3233## Reference Files3435- [breaking-changes.md](references/breaking-changes.md) - Complete migration guide with examples3637<!--38PROGRESSIVE DISCLOSURE GUIDELINES:39- Keep this file ~50 lines total (max ~150 lines)40- Use 1-2 code blocks only (recommend 1)41- Keep description <200 chars for Level 1 efficiency42- Move detailed docs to references/ for Level 3 loading43- This is Level 2 - quick reference ONLY, not a manual4445LLM WORKFLOW (when editing this file):461. Write/edit SKILL.md472. Format (if formatter available)483. Run: claude-skills-cli validate <path>494. If multi-line description warning: run claude-skills-cli doctor <path>505. Validate again to confirm51-->5253---54> Converted and distributed by [TomeVault](https://tomevault.io/claim/codatio) — claim your Tome and manage your conversions.55<!-- tomevault:4.0:skill_md:2026-04-11 -->
Run npx get-skill add tomevault-io/docusaurus-v2-to-v3-migration in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Use when migrating Docusaurus projects from v2 to v3 It is listed under Coding & Dev Tools on SkillMD.
SkillMD's automated safety review verdict for this skill is PASS. Independent scanners report: SkillSpector: CAUTION, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.
