All jobs

Upgrade a Docusaurus 2 Site to Docusaurus 3

Yes. An agent moves a Docusaurus 2 site to 3: Node 18, React 18, MDX 3, each page the MDX checker flags fixed, the config adjusted, and a PR with the build output.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads what the upgrade touches before it bumps anything. In a site like testing-library/testing-library-docs, package.json pins @docusaurus/core, @docusaurus/preset-classic and @docusaurus/remark-plugin-npm2yarn at ^2.0.1 (2.0.1 in the lock file) with react and react-dom at ^16.10.2, alongside prettier 2, husky 1, lint-staged 8 and four scripts left over from Docusaurus 1 (docusaurus-examples, docusaurus-write-translations, docusaurus-version, docusaurus-rename-version). docusaurus.config.js uses the classic preset with remarkPlugins: [[require('@docusaurus/remark-plugin-npm2yarn'), {sync: true}]], onBrokenLinks: 'log', a gtag block with a UA- tracking id, and an Algolia block. The content is 113 .mdx files and 4 .md files under docs/ and blog/, 10 of which contain HTML comments and 32 of which use the npm2yarn fence. netlify.toml builds with npm install; npm run format; npm run build and names no Node version; there is no .nvmrc and no GitHub workflow.

The order matters. Docusaurus 3 needs Node 18 or newer and React 18 or newer, so the agent first writes a .nvmrc with a current LTS, which Netlify reads, then runs npx docusaurus-mdx-checker on the v2 site to get the list of files MDX 3 will refuse to compile, with line numbers. In this site the likely hits are the ones the migration guide names: HTML comments, which become JSX comments, a { in prose that MDX 3 reads as an expression, indented blocks that used to be code, and lowercase custom tags. The agent fixes each file the checker lists, keeps the .mdx extension where the file uses components such as Tabs and TabItem, and re-runs the checker until it reports nothing.

Then the versions move together: @docusaurus/core, preset-classic and remark-plugin-npm2yarn to the same 3.x release, react and react-dom to 18, @mdx-js/react added at 3 as the preset's peer, and the four Docusaurus 1 scripts removed. npm run build is the real check, and npm run serve plus the browser in the sandbox is how the agent compares the pages that exercise the most syntax: a query page with Tabs, an example page with npm2yarn fences, the blog index with its feed, and src/pages/users.js with its customFields list. Config changes are small but real: mdx1Compat is left at its defaults so admonitions and heading ids keep working, and the Google Analytics UA- id is flagged in the pull request because the gtag plugin wants a G- measurement id and the agent cannot invent one.

Two tooling details would otherwise break the Netlify build. Prettier 2 does not understand MDX 3, and npm run format runs in the Netlify build command, so the agent adds *.mdx to .prettierignore rather than letting the formatter rewrite the files it just fixed. And onBrokenLinks: 'log' hides broken links; the agent leaves the setting but lists the links the build logs so the reviewer sees them. It runs npm run build one last time from a clean node_modules and lock file, as the migration guide suggests when a build misbehaves, before opening the pull request.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Upgrade this Docusaurus 2 site to Docusaurus 3. Read package.json, package-lock.json, docusaurus.config.js, sidebars.js, netlify.toml, src/css/custom.css, src/pages/index.js, src/pages/users.js and the components under src/components first. Add a .nvmrc with a current Node LTS. Run npx docusaurus-mdx-checker and fix every file it lists so it compiles under MDX 3: convert HTML comments to JSX comments, escape or code-wrap curly braces in prose, turn indented code into fenced blocks, and fix lowercase custom tags. Raise @docusaurus/core, @docusaurus/preset-classic and @docusaurus/remark-plugin-npm2yarn to the same 3.x release, react and react-dom to 18, add @mdx-js/react 3, and remove the Docusaurus 1 scripts. Add *.mdx to .prettierignore because Prettier 2 does not support MDX 3 and the Netlify build runs npm run format. Leave mdx1Compat at its defaults. Run npm install and npm run build until clean, serve the site and open in the browser a docs page with Tabs, a page with npm2yarn fences, the blog index and the users page to compare them with the v2 build, list any broken links the build logs, flag the UA- gtag id as needing a G- measurement id, then open a pull request with the checker output before and after, the build output, and the pages you checked.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request changes package.json, package-lock.json, docusaurus.config.js and every .mdx file the checker listed, and adds .nvmrc and .prettierignore. Its description quotes the docusaurus-mdx-checker output before and after, groups the content edits by kind (comments, braces, indented code, tags) with file counts, quotes the final npm run build output, and lists the pages opened in the browser with what was compared.

It separates what the agent did from what it could not: the analytics id needs a G- measurement id from whoever owns the property, Prettier stays at 2 with MDX ignored until a release that handles MDX 3, and onBrokenLinks stays at log with the logged links listed so a maintainer can decide whether to switch it to throw.

Before merging, a reviewer deploys the branch as a Netlify preview, clicks through the same pages on the preview, and checks the Algolia search still returns results against the rebuilt HTML, which the sandbox cannot verify against the hosted index.

Run it on every Docusaurus major release

A documentation team sends this body from its own server when a new Docusaurus major ships, with the repository in resources and a request_id that is a UUID v5 of the release tag, so a retried call returns the run already started. Each run reads its own site: one that already runs the MDX 3 line gets only the version bump and a build, and one that kept mdx1Compat on gets the content edits that let those flags be turned off.

Between majors, an automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt 'run npx docusaurus-mdx-checker on this pull request's changed files and post a review that lists any file that would not compile under MDX 3 with the line and the fix' starts one run per push. The trigger adds the pull request after the prompt and fills in nothing else, so a new doc with an HTML comment is caught in review rather than in the next upgrade.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

A Docusaurus 2 to 3 upgrade is mostly a content migration wearing a version bump: MDX 3 refuses syntax that MDX 1 tolerated, and the only way to know how many of a hundred pages are affected is to run the checker, fix, build and look. The agent does that loop in its own sandbox with a browser, compares the rendered pages, and keeps the formatter from undoing its edits, which is the step a laptop upgrade usually misses until Netlify fails.

The checker output, the build log, the screenshots and the diff stay with the run, so a reviewer sees which files changed and why, file by file. A team with several documentation sites runs the same request across all of them at once.

Frequently asked questions

Why not jump straight to the newest Docusaurus release?

The agent does move to the current 3.x release; the breaking step is leaving 2, not which 3.x lands. Node, React and MDX all change at that boundary, and everything after it on the 3.x line is a routine minor upgrade.

What does docusaurus-mdx-checker catch?

Compilation errors under MDX 3, with the file and line: HTML comments, stray curly braces, autolinks in angle brackets, indented code and the like. It reports only what fails to compile, so the agent also opens the rendered pages in a browser to catch layout changes it cannot see.

Will the Netlify build change?

Only by reading the new .nvmrc, which Netlify honours, and by skipping .mdx files in the format step. The build command in netlify.toml stays as it is, and the pull request says to deploy the branch preview before merging.

Does the search index need rebuilding?

The Algolia configuration in docusaurus.config.js is unchanged. The crawler indexes the new HTML on its next run, and the pull request asks the reviewer to search on the preview to confirm results still resolve to the same paths.

More Docusaurus jobs

More jobs like this: Upgrade dependencies weekly

Keep reading