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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Add Mermaid Diagrams to a Docusaurus Site (Docusaurus)
- Add Mermaid Diagrams to an Eleventy Blog (Eleventy)
- Add Mermaid Diagrams to a Hugo Docsy Site (Hugo)