All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading