docusaurus-v2-to-v3-migration

Stars1

Forks0

UpdatedJune 18, 2026 at 09:09

Use when migrating Docusaurus projects from v2 to v3 — upgrade @docusaurus/React/MDX/prism dependencies, rewrite MDX v1 syntax to v3 (escape bare { and <, fix autolinks), swap @tsconfig/docusaurus for @docusaurus/tsconfig, update Prism imports, and resolve React 18 breaking changes. Triggers on tasks involving MDX v1 to v3 migration, Docusaurus dependency updates, React 18 compatibility, or v2/v3 breaking changes.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

mcclowes

mcclowes/skills-docusaurus

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

16 files

SKILL.md

readonly

name	docusaurus-v2-to-v3-migration
description	Use when migrating Docusaurus projects from v2 to v3 — upgrade @docusaurus/React/MDX/prism dependencies, rewrite MDX v1 syntax to v3 (escape bare { and <, fix autolinks), swap @tsconfig/docusaurus for @docusaurus/tsconfig, update Prism imports, and resolve React 18 breaking changes. Triggers on tasks involving MDX v1 to v3 migration, Docusaurus dependency updates, React 18 compatibility, or v2/v3 breaking changes.
license	MIT
metadata	{"author":"mcclowes","version":"1.0.0"}

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

This migration edits dependencies and content across the project, so work on a clean tree and verify after the risky steps rather than at the end.

Back up: Commit or branch first (git switch -c migrate-v3) so you can diff and roll back.
Pre-check: Run npx docusaurus-mdx-checker to identify MDX issues and note the count.
Update deps: Upgrade all @docusaurus packages, React, MDX, prism-react-renderer
Fix MDX: Escape bare { < characters, convert GFM autolinks, use code fences. Then re-run npx docusaurus-mdx-checker and confirm it reports zero issues before moving on.
Update config: Replace @tsconfig/docusaurus with @docusaurus/tsconfig, update Prism imports
Test: Run npm start, then npm run build. If the build fails, read the error, fix it, and re-run until clean.

Reference Files

breaking-changes.md - Complete migration guide with examples

More from this repository

same repository

docusaurus-config

mcclowes/skills-docusaurus

Use when working with docusaurus.config.js/ts files — validate the config structure, set required fields (title/url/baseUrl), fix URL and baseUrl formats, add presets and plugins, configure navbar/footer/theme settings, and move unknown keys into customFields. Triggers on tasks involving docusaurus.config.js, docusaurus.config.ts, site configuration, URL formats, presets, or theme config.

2026-06-181

docusaurus-plugins

mcclowes/skills-docusaurus

Use when creating Docusaurus plugins — write remark transformers for markdown AST, rehype transformers for HTML/HAST, lifecycle plugins that add routes/webpack config/global data via loadContent and contentLoaded, theme plugins and swizzled components, and content plugins for custom data sources. Triggers on tasks involving custom remark/rehype plugins, content plugins, theme plugins, or Docusaurus lifecycle hooks.

2026-06-181

docusaurus-themes

mcclowes/skills-docusaurus

Use when swizzling Docusaurus theme components and editing theme elements — wrap or eject components from @docusaurus/theme-classic, override navbar/footer/sidebar/TOC/DocItem, place customised components under src/theme/, and choose safe (--wrap) vs full (--eject) swizzles. Triggers on tasks involving Docusaurus swizzling, theme component customization, navbar, footer, sidebar, or layout modifications.

2026-06-181

google-style-guide

mcclowes/skills-docusaurus

Use when writing or reviewing technical documentation to follow Google's documentation style guide — enforce active voice and present tense, apply sentence case to headings, fix list and procedure formatting, mark code/UI elements correctly, flag non-inclusive terminology, and remove time-specific phrasing. Triggers on tasks involving technical writing, doc review, style consistency, inclusive language, or formatting standards.

2026-06-181

docusaurus-documentation

mcclowes/skills-docusaurus

Use when looking up the latest Docusaurus documentation at https://docusaurus.io/docs — retrieving config option references, plugin/preset APIs, MDX and markdown-feature syntax, sidebar and routing setup, theming, and deployment instructions. Triggers on tasks involving Docusaurus APIs, markdown/MDX features, configuration options, sidebars, or best practices.

2026-06-171

name	docusaurus-v2-to-v3-migration
description	Use when migrating Docusaurus projects from v2 to v3 — upgrade @docusaurus/React/MDX/prism dependencies, rewrite MDX v1 syntax to v3 (escape bare { and <, fix autolinks), swap @tsconfig/docusaurus for @docusaurus/tsconfig, update Prism imports, and resolve React 18 breaking changes. Triggers on tasks involving MDX v1 to v3 migration, Docusaurus dependency updates, React 18 compatibility, or v2/v3 breaking changes.
license	MIT
metadata	{"author":"mcclowes","version":"1.0.0"}

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

This migration edits dependencies and content across the project, so work on a clean tree and verify after the risky steps rather than at the end.

Back up: Commit or branch first (git switch -c migrate-v3) so you can diff and roll back.
Pre-check: Run npx docusaurus-mdx-checker to identify MDX issues and note the count.
Update deps: Upgrade all @docusaurus packages, React, MDX, prism-react-renderer
Fix MDX: Escape bare { < characters, convert GFM autolinks, use code fences. Then re-run npx docusaurus-mdx-checker and confirm it reports zero issues before moving on.
Update config: Replace @tsconfig/docusaurus with @docusaurus/tsconfig, update Prism imports
Test: Run npm start, then npm run build. If the build fails, read the error, fix it, and re-run until clean.

Reference Files

breaking-changes.md - Complete migration guide with examples