All jobs

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

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

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

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

The same job on other stacks

Keep reading