# Add Mermaid Diagrams to a VitePress Site

Yes. An agent wires vitepress-plugin-mermaid into your VitePress config, draws the first diagrams in the pages that need them, builds the site, and opens a PR.

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

## What the agent does

The agent reads how the site is built before it adds a plugin. In a documentation site laid out like the `packages/docs` workspace of vuejs/pinia, `package.json` depends on `vitepress` 1.6.4, `vitepress-plugin-llms`, `typedoc-vitepress-theme` and `vitepress-translation-helper`, with a `predocs` script that runs `run-typedoc.mjs` to generate the API pages before `docs` (`vitepress dev .`) and `docs:build` (`vitepress build .`). The configuration is split: `.vitepress/config/index.ts` calls `defineConfig` with `...sharedConfig` and the `locales` map (English at the root, Chinese under `/zh/`, and five other languages that link to external sites), `shared.ts` sets `appearance: 'dark'`, the sitemap, Shiki themes (`dracula-soft` and `vitesse-light`), custom attribute delimiters (`%{` and `}%`), a custom `slugify`, the `head` scripts and the `vitepress-plugin-llms` plugin, and `en.ts` and `zh.ts` hold each locale's nav and sidebar. `.vitepress/theme/index.ts` extends `DefaultTheme` with layout slots for sponsors and a translation-status banner, `vite.config.ts` adds a plugin that copies the built `pinia.js` into the site, `netlify.toml` builds with `pnpm run docs:build` on Node 24 and publishes `.vitepress/dist`, and the root `package.json` pins `pnpm@12.11.2`. The repository's `ci.yml` ignores `packages/docs/**`, so the Netlify build is the only check the docs get.

The plugin is `vitepress-plugin-mermaid` (2.0.17 on npm), which declares `mermaid` at `10 || 11` and `vitepress` `^1` as peers, so the agent adds `mermaid` at 11 to the docs workspace rather than the newest 12 that npm would resolve, and says so in the pull request. In `config/index.ts` it wraps the existing call as `withMermaid(defineConfig({...}))`, keeping the spread of `sharedConfig` and the `locales` exactly as they are, and adds a `mermaid` options object; the plugin forces a dark Mermaid theme when the site's appearance is dark, which this site defaults to, so the `theme` it sets there applies to light mode only. The plugin renders any fenced block whose language is `mermaid`, and the `markdown.attrs` delimiters the site customises do not clash with that.

Then it draws the diagrams the prose is already describing. In `core-concepts/plugins.md`, where a plugin receives a context of `pinia`, `app`, `store` and `options` and returns properties to add to a store, a `flowchart` shows that path. In `ssr/index.md`, a `sequenceDiagram` shows the server creating the pinia instance, rendering, serialising state into the page and the client hydrating it. In `core-concepts/index.md`, a small graph shows state, getters and actions on one store. Each diagram is a fenced `mermaid` block kept to the terms the page already uses, and the agent puts the same block in the `zh/` copy of each page, since that locale is maintained in the repository and the translation helper compares the two. It does not touch the generated API pages or the typedoc step.

The agent runs `pnpm install` from the repository root, then the Netlify command, `pnpm run docs:build`, which runs the typedoc step first. It serves the output with `vitepress preview`, opens the three pages in its browser in both appearances to see the diagrams render and switch theme, and keeps the screenshots. If the Vite dev server fails on a dependency the plugin loads lazily, the agent adds it to `vite.optimizeDeps.include` in the VitePress config and says why. It also checks the `llms.txt` output that `vitepress-plugin-llms` writes, where a diagram appears as its Mermaid source, which is the right thing for a text reader.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Mermaid diagrams to this VitePress site. Read packages/docs/package.json, every file under packages/docs/.vitepress/config, packages/docs/.vitepress/theme/index.ts, packages/docs/vite.config.ts, netlify.toml and the root package.json first. Add vitepress-plugin-mermaid and a mermaid version that satisfies its peer range to the docs workspace, wrap the existing defineConfig call in config/index.ts with withMermaid without changing the shared config or the locales, and add a mermaid options object. Draw a flowchart of the plugin context in core-concepts/plugins.md, a sequence diagram of server rendering and client hydration in ssr/index.md, and a small graph of state, getters and actions in core-concepts/index.md, each as a fenced mermaid block, and mirror each block into the zh copy of the page. Run pnpm install and pnpm run docs:build from the root, preview the site, check the three pages in light and dark appearance, add any lazily loaded dependency to optimizeDeps only if the dev server needs it, and open a pull request that quotes the build output and includes the screenshots.",
  "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 `packages/docs/package.json` and `pnpm-lock.yaml`, `packages/docs/.vitepress/config/index.ts`, and six Markdown pages (three English, three under `zh/`). Its description quotes `pnpm run docs:build` from the sandbox, explains the Mermaid 11 pin against the plugin's peer range, and shows the three diagrams rendered in both appearances.

A reviewer reads the diagrams against the prose above them, which is the real review: a sequence diagram that puts hydration before serialisation is worse than no diagram. The reviewer also confirms the config wrapper left `sharedConfig` and `locales` untouched and that the Netlify deploy preview, which runs the same command, builds green.

From then on a new diagram is a fenced block in Markdown, with no component to import, and the translation helper flags the Chinese page as out of date until the block is mirrored.

## Run it on every documentation site repository

A team with several VitePress sites sends this body once per repository from its own server, each `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 site: one with a single `config.ts` gets the wrapper there, and one without a second locale gets no mirrored pages.

An automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if this pull request adds a mermaid block to an English page, check that the zh copy has the same block and that the site builds, and post a review" runs once per pull request. The trigger adds the pull request after the prompt and fills in nothing else. Only work by an owner, member or collaborator fires it.

## Why run it on Rush?

The configuration half of this change is a wrapper and a version pin, and the half that matters is whether the diagrams say what the pages say. The agent reads the pages before it draws, builds the site with the same command as the deploy, renders every diagram in both appearances in its own browser, and keeps the screenshots and every command with the pull request, so the reviewer judges the diagrams and not the setup.

A reviewer reads three diagrams and a config diff. A team that documents several packages starts the same request across all of them at once.

## Frequently asked questions

### Why Mermaid 11 and not the latest?

`vitepress-plugin-mermaid` 2.0.17 declares `mermaid` at `10 || 11` as a peer dependency. Installing 12 would warn or fail under pnpm's peer checks and could break at runtime, so the agent pins 11 and notes it in the pull request for when the plugin widens the range.

### Does it work with the dark appearance?

Yes. The plugin forces a dark Mermaid theme when the site is dark, which is this site's default, and uses the configured theme for light mode. The screenshots in the pull request show each diagram in both.

### Will it change the generated API pages?

No. The typedoc step still runs before the build and its output is untouched; the diagrams go only into the three hand-written pages and their Chinese copies.

### What about the llms.txt output?

`vitepress-plugin-llms` writes the Markdown source, so a diagram appears there as its Mermaid text, which is a readable description of the same structure. The agent checks that file after the build and leaves it as the plugin produces it.

## More VitePress jobs

- [Add Open Graph Tags to a VitePress Blog](https://getrush.ai/run/add-open-graph-tags/vitepress/)
- [Add Reading Time to a VitePress Blog](https://getrush.ai/run/add-reading-time/vitepress/)
- [Add Search to a VitePress Blog With a Custom Theme](https://getrush.ai/run/add-search/vitepress/)

## The same job on other stacks

- [Add Mermaid Diagrams to a Docusaurus Site](https://getrush.ai/run/add-mermaid-diagrams/docusaurus/)
- [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/)

## 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/)
