# Add Mermaid Diagrams to a Docusaurus Site

Yes. An agent moves a Docusaurus 2 site to a Mermaid-capable release, adds the theme and config, draws diagrams from your prose, builds the site and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-mermaid-diagrams/docusaurus/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts with the version question, because Mermaid support arrived in Docusaurus 2.2.0 and many 2.x sites sit below it. In a site laid out like testing-library/testing-library-docs, `package.json` asks for `@docusaurus/core` and `@docusaurus/preset-classic` at `^2.0.1`, and `package-lock.json` (lockfile version 2) resolves both to exactly 2.0.1, beside `@docusaurus/remark-plugin-npm2yarn` 2.0.1, React 16.13.1 and Prettier 2.2.1 run through `kcd-scripts`. `.node-version` pins Node 16.14, which is also the floor for the last 2.x release. `docusaurus.config.js` holds a classic preset with `docs` at `./docs`, `sidebarPath: './sidebars.js'`, a blog with feeds, a `colorMode` block that respects the system scheme, an Algolia block and `onBrokenLinks: 'log'`; `src/css/custom.css` already defines `[data-theme='dark']` and `[data-theme='light']` variables. There are no GitHub workflows: `netlify.toml` builds with `npm install; npm run format; npm run build`.

The agent runs `npm install @docusaurus/core@2.4.3 @docusaurus/preset-classic@2.4.3 @docusaurus/remark-plugin-npm2yarn@2.4.3 @docusaurus/theme-mermaid@2.4.3`, so all four packages move together to the final 2.x release and the lockfile records it; the theme package must match the core version exactly, which is why it does not simply add the theme on top of 2.0.1. In `docusaurus.config.js` it sets `markdown: { mermaid: true }`, appends `'@docusaurus/theme-mermaid'` to `themes`, and adds `themeConfig.mermaid.theme` with `light: 'neutral'` and `dark: 'dark'` so diagrams follow the site's existing colour-mode switch rather than rendering a white box on a dark page.

Then it draws from what the pages already say. `docs/intro.mdx` describes one core package, DOM Testing Library, wrapped by framework packages for React, Angular and Vue, plus a Cypress plugin and a React Native implementation; that becomes a `graph TD` block under "The solution", with each wrapper linking to its own intro page. `docs/queries/about.mdx` lists the query priority (`getByRole`, then `getByLabelText`, `getByPlaceholderText`, `getByText`, `getByDisplayValue`, then the semantic queries and last `getByTestId`) as nested prose; a `flowchart` beside that list turns it into the decision a reader actually makes. The agent keeps the prose, because the diagram is an addition and screen readers get the text. A third diagram is only added where a page already narrates a sequence, such as the `findBy*` wait in `docs/dom-testing-library/api-async.mdx`; it does not scatter diagrams for their own sake.

It runs `npm run build` and reads the output for broken links and MDX errors, opens the built pages in the sandbox browser in both colour modes, and runs `npm run format` so Prettier 2 with the repository's config leaves the fenced blocks as they are. The pull request opens when the build is clean.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add Mermaid diagrams to this Docusaurus 2 site. Read package.json, package-lock.json, .node-version, docusaurus.config.js, sidebars.js, src/css/custom.css, netlify.toml and the docs directory first, and find which Docusaurus version the lockfile actually resolves. Mermaid needs Docusaurus 2.2.0 or later, so if the site is below that, update @docusaurus/core, @docusaurus/preset-classic and every other @docusaurus package to the same latest 2.x release together with @docusaurus/theme-mermaid at that exact version. Set markdown.mermaid to true, add the theme to themes, and set themeConfig.mermaid.theme for light and dark modes. Add two or three diagrams where a page already describes a structure or a sequence in prose (the package family in the intro, the query priority order), keeping the prose in place. Run npm run build and npm run format until both are clean, check the diagrams in both colour modes, and open a pull request that explains the version move and lists each diagram with the page it is on.",
  "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` and `package-lock.json` for the Docusaurus packages, `docusaurus.config.js` for the `markdown`, `themes` and `themeConfig.mermaid` entries, and two or three MDX files under `docs/` with fenced `mermaid` blocks. Its description names the version the lockfile resolved before and after, quotes the end of the `npm run build` output, and lists each diagram with the sentence it illustrates.

A reviewer checks the version jump first, since a 2.0 to 2.4 move touches the whole site: the Netlify preview that builds from the branch is the quickest look. Then they read each diagram against its prose for accuracy, because a wrong arrow in a priority chart misleads more than a missing one, and confirm the dark theme is readable.

From then on, any contributor writes a ```` ```mermaid ```` block in Markdown and gets a rendered diagram, with no image files to regenerate when the text changes.

## Run it on every docs site added to the org

A team that runs several documentation sites sends this body once per repository from its own server, each a `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own lockfile: a site already on 2.4 gets only the theme and the diagrams, and a site on Docusaurus 3 gets the matching 3.x theme package instead of a 2.x one.

Give the key a `webhook_url` and Rush POSTs `run.completed` to it when the turn ends, signed per Standard Webhooks, with `data.session_url` to read the pull request link from. A follow-up on `POST /o/{org}/sessions/{id}/messages`, sent once the turn has finished, wakes the same sandbox to redraw one diagram or move it to another page.

## Why run it on Rush?

Enabling Mermaid is a few lines, but on a site that has not been upgraded in a while the real work is the version move that makes those lines valid, and the only honest check is a full `npm run build` plus a look at the rendered pages in both colour modes. The agent does that in its own sandbox with the site's own Node version, and the build output travels with the pull request.

The diagrams are drawn from the pages' own text, which means reading the docs, not pasting a sample chart. A team with more than one site starts the same request against each repository at once and reviews a set of small pull requests instead of scheduling the upgrade.

## Frequently asked questions

### Why does the site have to move to a newer Docusaurus release?

Mermaid rendering lives in `@docusaurus/theme-mermaid`, which shipped with Docusaurus 2.2.0 in October 2022, and the theme package only installs against the same core version. A lockfile that resolves `^2.0.1` to 2.0.1 therefore has no Mermaid support until core and preset are updated. The agent updates to the last 2.x release, not to 3.x, so the site's React 16 and existing config stay valid.

### Will the diagrams respect dark mode?

Yes, when `themeConfig.mermaid.theme` names a theme for each mode. The agent sets a light theme and a dark theme and switches the built site between them in the sandbox browser, since the default light rendering is hard to read on a dark background.

### Does Prettier rewrite the Mermaid blocks?

No. Prettier leaves the contents of a fenced code block alone, and `npm run format` runs on the branch so the result matches what the Netlify build command does on deploy. The agent also keeps the `lint-staged` and `husky` setup untouched.

### Which pages get a diagram?

Only pages that already describe a structure or an order in prose: the package family in the intro and the query priority list are the clear cases. The prose stays, so the text remains the source of truth and the diagram is an aid. The pull request lists each one, and a follow-up message can add or remove a diagram without starting over.

## More Docusaurus jobs

- [Add PWA Support to a Docusaurus Site](https://getrush.ai/run/add-pwa-support/docusaurus/)
- [Add Redirects for Moved Pages to a Docusaurus Site](https://getrush.ai/run/add-redirects/docusaurus/)
- [Add a Typo Check to a Docusaurus Site in CI](https://getrush.ai/run/add-typo-check/docusaurus/)

## The same job on other stacks

- [Add Mermaid Diagrams to an Eleventy Blog](https://getrush.ai/run/add-mermaid-diagrams/eleventy/)
- [Add Mermaid Diagrams to a Hugo Docsy Site](https://getrush.ai/run/add-mermaid-diagrams/hugo/)
- [Add Mermaid Diagrams to a Jekyll Blog on GitHub Pages](https://getrush.ai/run/add-mermaid-diagrams/jekyll/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
