agentsclimarketplace
Sign in

Docusaurus v2 to v3 migration

Skill mcclowes/skills-docusaurus/skills/docusaurus-v2-to-v3-migration

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.From its SKILL.md

Install
npx -y skills add mcclowes/skills-docusaurus --skill docusaurus-v2-to-v3-migration

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

1.9 KB, as published. Nobody here has run it

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.

  1. Back up: Commit or branch first (git switch -c migrate-v3) so you can diff and roll back.
  2. Pre-check: Run npx docusaurus-mdx-checker to identify MDX issues and note the count.
  3. Update deps: Upgrade all @docusaurus packages, React, MDX, prism-react-renderer
  4. 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.
  5. Update config: Replace @tsconfig/docusaurus with @docusaurus/tsconfig, update Prism imports
  6. Test: Run npm start, then npm run build. If the build fails, read the error, fix it, and re-run until clean.

Reference Files

Keep looking

Skills are one crate of 627,801. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.