All jobs

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

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

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

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

The same job on other stacks

Keep reading