# Add Mermaid Diagrams to a Starlight Docs Site

Yes. An agent wires Mermaid into your Starlight site, draws the flows your guides describe in prose, keeps the diagrams readable in dark mode and opens a PR.

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

## What the agent does

The agent reads the docs package before touching it, since a Starlight site inside a monorepo has more moving parts than a standalone one. In a site like the `docs/` workspace of openai/openai-agents-js, `pnpm-workspace.yaml` lists `docs` beside `packages/*` and `examples/*`, and `docs/package.json` depends on `astro` 7, `@astrojs/starlight` 0.42, `@astrojs/mdx`, `starlight-typedoc`, `starlight-llms-txt` and Tailwind. `docs/astro.config.mjs` sets `site` and a `base` of `openai-agents-js`, pins `markdown.processor` to a `unified()` pipeline so a local `rehypeCanonicalHeadingIds` plugin can run, and registers `starlight({...})` with four locales, custom `Sidebar`, `PageTitle` and `SiteTitle` components, six TypeDoc plugins and `expressiveCode.themes` of `houston` and `one-light`, followed by `mdx({ optimize: true })`. The guides live in `docs/src/content/docs/guides/` and are copied into `ja/`, `zh/` and `ko/` by the `docs:translate` script. The only diagrams on the site are three PNGs loaded from a CDN in the voice guides and one local image in the sandbox concepts page; the agent loop in `running-agents.mdx` and the two orchestration patterns in `multi-agent.md` are described as numbered lists and a table.

The integration is `astro-mermaid`, which turns a ```` ```mermaid ```` fence into a `<pre class="mermaid">` element at build time and renders it to SVG in the browser with the `mermaid` package, so the build needs no headless browser. The agent adds both packages to `docs/package.json` with `pnpm --filter docs add astro-mermaid mermaid`, and registers `mermaid({ theme: 'default', autoTheme: true })` in `integrations` ahead of `starlight()`, the order its README requires. With `autoTheme` on, the integration follows the `data-theme` attribute, and Starlight's `ThemeProvider` writes exactly that attribute on the `html` element as `light` or `dark`, so a diagram repaints when a reader flips the theme picker. Because this config pins `markdown.processor` to `unified()`, the agent confirms in the build output which pipeline the integration attached to, since it supports both that path and Astro 7's default engine.

Then the diagrams, which is the part worth reading. From the numbered list under "The agent loop" in `running-agents.mdx` the agent draws a flowchart: call the model, inspect the response, three branches for final output, handoff and tool calls, the loop edge back to the model call, and the `MaxTurnsExceededError` exit. From the table in `multi-agent.md` it draws two small diagrams side by side, a manager calling specialists through `agent.asTool()` and a triage agent handing off to a specialist that keeps the conversation, and from `handoffs.mdx` a sequence diagram of the `transfer_to_refund_agent` tool call. Each fence goes directly under the prose it illustrates, with node labels taken from the page's own terms, and the English pages get them first. The `ja/`, `zh/` and `ko/` copies are produced by the translate script, which the sandbox cannot run without the maintainers' key, so the agent copies the same fences into the three translated pages with labels left in English and says so in the pull request, so the next translation pass can localize them.

The check is the site's own build. `.github/workflows/docs.yml` runs `pnpm build:ci`, `pnpm docs:scripts:check`, `pnpm -F docs-code build-check` and `pnpm docs:build` on every pull request that touches `docs/**`, so the agent runs the same four commands in its sandbox, with `pnpm install` first, since `docs:build` runs TypeDoc over the six package entry points and needs the packages built. It then greps `docs/dist/guides/running-agents/index.html` for `class="mermaid"`, serves `docs/dist` and opens the page in its browser in both themes, keeping a screenshot of each. A diagram that fails to parse renders as an error box in the browser rather than failing the build, which is why the browser pass matters.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Mermaid diagram support to the Starlight docs site in this repository. Read docs/package.json, docs/astro.config.mjs, pnpm-workspace.yaml, .github/workflows/docs.yml and the guides under docs/src/content/docs/guides first. Install astro-mermaid and mermaid in the docs workspace and register the mermaid integration with autoTheme before starlight in astro.config.mjs. Add a mermaid fence that draws the agent loop described in running-agents.mdx, two fences for the agents-as-tools and handoff patterns described in multi-agent.md, and a sequence diagram of a handoff in handoffs.mdx, using the pages' own terms as labels; copy the fences into the ja, zh and ko versions with English labels and note that in the pull request. Run pnpm install, pnpm build:ci, pnpm docs:scripts:check, pnpm -F docs-code build-check and pnpm docs:build, confirm the built HTML contains the mermaid elements, open the pages in the browser in light and dark themes, and open a pull request with the commands, their output and 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 `docs/package.json`, `pnpm-lock.yaml`, `docs/astro.config.mjs` and three guide pages in each of the four locales, twelve content files in all, and adds nothing else. Its description quotes the four build commands with their output, lists the pages that gained a diagram, embeds the light and dark screenshots from the run's record, and names the translated copies whose labels are still in English.

A reviewer reads the diagrams against the prose above them, since a flowchart that disagrees with the list it sits under is worse than no flowchart, and checks the integration order in the config. The Actions workflow runs the same build on the pull request, so the merge decision rests on whether the diagrams say the right thing, not on whether they render.

## Run it on every documentation site repository

A team with several Starlight sites sends this body once per repository from its own server, each `POST /o/{org}/sessions` naming one repository in `resources` with 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 guides and draws only what the prose describes: a site with a deployment page gets a pipeline diagram, a site with no process to draw gets the integration and one example fence in its contributing guide.

An automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if this pull request adds a guide that describes a sequence of steps with no diagram, suggest a mermaid fence for it as a review comment" keeps new pages to the same standard. The trigger adds the pull request after the prompt and fills in nothing else, and only work by an owner, member or collaborator fires it.

## Why run it on Rush?

The configuration is a few lines, and the work is in the diagrams and the build. The agent reads the flows from the pages that describe them, writes fences that use the same words, runs the full docs pipeline in its own sandbox, including the TypeDoc steps that make the build slow on a laptop, and opens the result in a browser in both themes, with every command and screenshot kept in the run's record.

A docs site with translations multiplies every content change by its locale count, and a site with a pinned Markdown processor can take an integration differently than its README assumes. The agent handles both from what it finds, copies the fences to the three other locales, confirms which pipeline the integration attached to, and writes down in the pull request what is left for the translators.

## Frequently asked questions

### Does the build need a browser?

No. `astro-mermaid` leaves a `<pre class="mermaid">` in the HTML and renders it client-side with the bundled `mermaid` package. `rehype-mermaid` renders SVG at build time instead, but needs Playwright in CI, which the pull request mentions as the option for a site that wants diagrams without JavaScript.

### Will diagrams follow the dark theme?

Yes. With `autoTheme` on, the integration reads the `data-theme` attribute on the `html` element, which Starlight's theme picker sets to `light` or `dark`, and re-renders the diagram with the matching Mermaid theme when it changes. The run's screenshots show both.

### What about the translated pages?

The translate script that produces them runs with the maintainers' model key outside the sandbox, so the agent copies the fences into the `ja`, `zh` and `ko` pages with English labels and lists those files in the pull request. The next translation pass can localize the labels without touching the diagram structure.

### Does the pinned unified() processor get in the way?

The site pins `markdown.processor` to `unified()` for a local rehype plugin. `astro-mermaid` supports a unified pipeline as well as Astro 7's default engine, and the agent confirms in the build log which one it attached to and that the `<pre class="mermaid">` elements appear in `docs/dist`.

### Can it draw diagrams for pages I choose?

Yes. Name the pages and the flows in `input`, or tell it to find every numbered list of steps under `guides/` and propose a diagram for each. It only draws what the prose supports; it does not invent a flow a page does not describe.

## More Starlight jobs

- [Generate an API Reference From an OpenAPI Spec in a Starlight Site](https://getrush.ai/run/add-openapi-docs/starlight/)
- [Add an RSS Feed to a Starlight Docs Site](https://getrush.ai/run/add-rss-feed/starlight/)
- [Add a Typo Check to Starlight Docs](https://getrush.ai/run/add-typo-check/starlight/)

## The same job on other stacks

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

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