# Add Mermaid Diagrams to an Eleventy Blog

Yes. An agent teaches Eleventy's Markdown to pass mermaid fences through untouched, ships the renderer only on pages that draw, builds the site and opens a PR.

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

## What the agent does

The agent reads the build before it adds a dependency, because Eleventy has two places a fenced code block can be intercepted. In a blog like 11ty/eleventy-base-blog, `package.json` is at version 9.0.0 with `"type": "module"`, `engines.node >=18`, and dev dependencies `@11ty/eleventy` ^3.1.8, `@11ty/eleventy-img` ^7.1.1, `@11ty/eleventy-plugin-rss` ^3.1.0, `@11ty/eleventy-plugin-syntaxhighlight` ^5.0.2, `luxon`, `prismjs` and `zod`, with `.nvmrc` at 22. `eleventy.config.js` registers the syntax highlight plugin with `preAttributes: { tabindex: 0 }`, two bundles named `css` and `js` written to `dist` that collect every `<style>` and `<script>` on a page, the RSS `feedPlugin` for `/feed/feed.xml`, the image transform plugin, `IdAttributePlugin`, and a `drafts` preprocessor; `markdownTemplateEngine` is `njk` and the input directory is `content`. `_includes/layouts/base.njk` inlines `css/index.css` into the bundle and includes the `heading-anchors` web component from `node_modules` as an inline module script, then renders the `js` bundle as a file with `getBundleFileUrl`. `_includes/layouts/post.njk` adds `prism-okaidia.css` and `css/prism-diff.css` to the per-page CSS bundle only on posts, and `content/blog/firstpost.md` carries a `diff-js` fence the highlighter turns into a diff block. `css/index.css` switches its custom properties under `@media (prefers-color-scheme: dark)`.

The highlighter is the first thing to get out of the way. Prism has no `mermaid` grammar, so a fence tagged `mermaid` would come out as a `<pre class="language-mermaid">` block of plain text and the renderer would never find it. The agent amends the Markdown library with `eleventyConfig.amendLibrary("md", ...)` and wraps the `fence` renderer rule: a token whose `info` is `mermaid` returns `<pre class="mermaid">` with the escaped source, every other fence falls through to the original rule, which is where the syntax highlight plugin's highlighter still runs. Doing it in the fence rule rather than in a paired shortcode means authors write the same three backticks they write for JavaScript and nothing in `markdownTemplateEngine` changes.

Then it decides how the renderer reaches the page, and the blog's own bundle makes the choice easy. The base layout already ships one `js` bundle file per page, so the agent adds `mermaid` as a dependency and, in `post.njk`, a `{% js %}` block that imports the library and calls `mermaid.initialize({ startOnLoad: false, theme: ... })` followed by `mermaid.run()`, guarded by `document.querySelector(".mermaid")` so posts without a diagram download nothing. The theme follows the stylesheet: `window.matchMedia("(prefers-color-scheme: dark)")` picks `dark` or `default`, the same media query `index.css` uses. Mermaid's own `package.json` asks for Node 22.12 or newer, which `.nvmrc` at 22 meets and the blog's `engines.node >=18` does not promise, so the agent raises that floor in the same change. For the import itself the agent reads mermaid's `dist/`: the ESM entry `mermaid.esm.min.mjs` is small but pulls a `chunks/` directory of dynamic imports for each diagram type, so self-hosting means a passthrough copy of that whole directory, while `mermaid.min.js` is a single file. The pull request copies the single file through `addPassthroughCopy` into `/js/` and loads it with a classic `<script>` before the init call, and names the ESM-plus-chunks copy and the CDN URL as the two alternatives, with the trade of one request against many.

Then it draws and builds. The agent adds one diagram to an existing post rather than a demo page: `content/blog/fourthpost/fourthpost.md` already has an image and a nested directory, so a `flowchart LR` describing the build steps goes there, and `content/blog/firstpost.md` keeps its `diff-js` block to prove the highlighter still runs beside the new rule. `npm run build` writes `_site/`, and the agent reads `_site/blog/fourthpost/index.html` for a `<pre class="mermaid">` with the source intact and escaped, `_site/blog/firstpost/index.html` for the Prism classes, and the `js` bundle file for the init code only on the post that has a diagram. It opens the built page in its browser, waits for the `svg` inside the `pre`, and screenshots it in both colour schemes with the `prefers-color-scheme` emulation, so the pull request shows the drawn diagram. The Atom feed is checked too: `feedPlugin` renders post content into `feed.xml`, so the fence appears there as its source inside `<pre>`, which the agent leaves as it is and explains.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add Mermaid diagram support to this Eleventy blog. Read package.json, .nvmrc, eleventy.config.js, _includes/layouts/base.njk and post.njk, css/index.css and the posts under content/blog first. Amend the Markdown library's fence rule so a fence tagged mermaid renders as a pre element with class mermaid and escaped source, and every other fence still goes through the syntax highlight plugin. Add the mermaid package and load it only on pages that contain a diagram, through the existing per-page js bundle, with startOnLoad off and an explicit run, choosing the dark or default theme from the same prefers-color-scheme query the stylesheet uses. Read mermaid's dist directory and choose between the single-file build, the ESM entry with its chunks directory, and a CDN URL; say why in the pull request. Add one diagram to an existing post and keep the diff-js fence in the first post as a control. Run npm run build, read the built HTML for both posts and the bundle, open the diagram page in the browser in light and dark schemes and screenshot the rendered SVG, note how the fence appears in the Atom feed, and open a pull request.",
  "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

A pull request that changes `eleventy.config.js`, `_includes/layouts/post.njk`, `package.json` and `package-lock.json`, and adds one diagram to an existing post. The description shows the fence rule beside the highlighter registration, the built HTML of the diagram post and the control post, the size of the bundle file on each, and two screenshots of the rendered SVG in light and dark schemes from the sandbox browser.

The repository has a sample GitHub Pages workflow with a `.sample` suffix and no live check, so the build output in the run's record is the evidence. A reviewer looks at the screenshots, decides whether to self-host the single file or the ESM chunks, and whether the feed should carry the diagram source or a note, both of which the description lays out without choosing for them.

## Run it on every pull request that adds a diagram

Once merged, an automation in the Project with the repository, with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "if this pull request adds or changes a mermaid fence, build the site, open the page in the browser, and comment with a screenshot of the rendered diagram or the parse error mermaid reports", gives every diagram a rendered check before a human reads the source. The trigger adds the pull request after the prompt and fires only for work by owners, members and collaborators.

For a second Eleventy site, send this body again 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. The run reads that site's config, so a site on `markdownTemplateEngine: liquid` or one without the bundle plugin gets the renderer wired through whatever its layout already does.

## Why run it on Rush?

Mermaid in a static site is a few lines, and all of them are easy to get wrong in a way the source diff hides: a fence the highlighter swallowed, a script loaded on every page of a blog that has one diagram, a diagram unreadable in dark mode because the theme was fixed to light. The agent builds the site in its own sandbox, reads the generated HTML, and opens the page in a real browser in both colour schemes, so the pull request shows the drawn SVG rather than describing it.

Every command and screenshot stays with the run, and the pull request quotes the build. The same change across a team's Eleventy sites costs no more attention than one, because each run reads that site's own layout and bundle setup and opens its own pull request.

## Frequently asked questions

### Will the syntax highlighter still handle my other code blocks?

Yes. The fence rule only intercepts a fence whose info string is `mermaid` and hands every other fence to the original rule, where the syntax highlight plugin's highlighter runs as before. The first post's `diff-js` block is kept as a control and its built HTML is quoted in the pull request.

### Does every page download the mermaid library?

No. The init code lives in a `{% js %}` block on the post layout guarded by a check for a `.mermaid` element, and the bundle plugin writes one file per page, so a post without a diagram gets a bundle without the renderer. The pull request quotes the bundle size on the diagram post and on a plain post.

### Do the diagrams follow dark mode?

Yes. The init reads the same `prefers-color-scheme: dark` query that `css/index.css` uses for its custom properties and passes `dark` or `default` as the mermaid theme. The two screenshots in the pull request come from the sandbox browser with each scheme emulated.

### Why not render the diagrams to SVG at build time?

Build-time rendering needs a headless browser in the build, which the GitHub Pages workflow sample does not have and which would slow every deploy. The client-side approach matches how the blog already loads its heading-anchors script, and the pull request names the build-time option for a team that wants diagrams in the feed and with JavaScript off.

### What shows up in the Atom feed?

The diagram's source inside a `<pre>` element, because the feed plugin renders post content and the browser-side renderer never runs in a reader. The pull request shows that entry and leaves it, since a reader cannot run mermaid either way.

## More Eleventy jobs

- [Add Open Graph and Twitter Card Tags to an Eleventy Blog](https://getrush.ai/run/add-open-graph-tags/eleventy/)
- [Add Pagination to an Eleventy Blog Archive](https://getrush.ai/run/add-pagination/eleventy/)
- [Add Reading Time to an Eleventy Blog](https://getrush.ai/run/add-reading-time/eleventy/)

## The same job on other stacks

- [Add Mermaid Diagrams to a Hugo Docsy Site](https://getrush.ai/run/add-mermaid-diagrams/hugo/)
- [Add Mermaid Diagrams to a Jekyll Blog on GitHub Pages](https://getrush.ai/run/add-mermaid-diagrams/jekyll/)
- [Add Mermaid Diagrams to an mdBook](https://getrush.ai/run/add-mermaid-diagrams/mdbook/)

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