What the agent does
The agent starts from the constraint that decides the design: GitHub Pages builds a blog like barryclark/jekyll-now with the github-pages gem, version 233 today, which pins Jekyll 3.10.0, kramdown 2.4.0 with the GFM parser and Rouge, and a fixed list of plugins. A Mermaid plugin is not on that list, and the repository has no Gemfile to add one to, since .gitignore excludes it and the README's workflow is to fork and let Pages build. So whatever renders the diagrams has to happen in the browser. The agent reads _config.yml to see kramdown set to input: GFM with syntax_highlighter: rouge, _layouts/default.html to see where scripts are included, which is analytics.html at the end of the body, _layouts/post.html for how a post is wrapped, and style.scss for where styles live.
Then it checks what a fenced block actually becomes, by building the site in its sandbox with gem install github-pages and a post containing a ```mermaid fence. Rouge has no Mermaid lexer, and under this Jekyll the block comes out as a plain <pre><code class="language-mermaid"> with the diagram text inside, escaped as HTML. That is the hook the script needs: it finds every code.language-mermaid, builds a <pre class="mermaid"> whose text content is the code's text content, which undoes the escaping, and replaces the original block with it. A fenced block in a post that never loads the script stays a code block, which is the fallback for feed readers and for anyone with scripts off.
The agent writes _includes/mermaid.html: a <script type="module"> that imports Mermaid from jsDelivr by its pinned ESM path, https://cdn.jsdelivr.net/npm/mermaid@12.3.0/dist/mermaid.esm.min.mjs, does the replacement above, calls mermaid.initialize({ startOnLoad: false, theme: 'neutral' }) and then await mermaid.run(), which renders every pre.mermaid on the page. startOnLoad is off so the replacement runs before rendering rather than racing it, and securityLevel stays at its default, strict, so a diagram cannot carry HTML or click handlers. _layouts/default.html includes it after analytics.html, wrapped in {% if page.mermaid %}, so the module is fetched only on a post whose front matter says mermaid: true; the built index and the posts without the flag contain no reference to it. style.scss gets a rule that keeps the rendered SVG inside the 740-pixel container, and a new post under _posts/ shows a flowchart and a sequence diagram with the flag set and explains the opt-in in a sentence.
The build is the first proof and the browser is the second. The agent runs github-pages build under a UTF-8 locale, reads _site/<post>/index.html to confirm the language-mermaid block and the single module script are there and that _site/index.html has none, then serves _site on a local port and opens the post in the sandbox's browser, waits for the svg inside pre.mermaid, and screenshots it for the pull request. The old include files, the other layouts and _config.yml are untouched.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "codex",
"input": "Add Mermaid diagrams to this Jekyll blog, which GitHub Pages builds with the github-pages gem and no custom plugins. Read _config.yml, .gitignore, README.md, _layouts/default.html, _layouts/post.html, _includes/analytics.html, style.scss and the files under _posts/ first. Do not add a Gemfile or a plugin. Write _includes/mermaid.html as a module script that imports mermaid from jsDelivr at a pinned version, replaces each code.language-mermaid block with a pre.mermaid holding its text, calls mermaid.initialize with startOnLoad false and the default securityLevel, then mermaid.run. Include it from _layouts/default.html only when page.mermaid is true. Add a style that keeps the rendered SVG within the container, and a sample post with mermaid: true showing a flowchart and a sequence diagram. In the sandbox install the github-pages gem, run github-pages build with a UTF-8 locale, confirm the built post has the code block and one module script and the index has none, serve _site, open the post in the browser, wait for the SVG and screenshot it. Open a pull request with the build output and the screenshot.",
"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
What comes back is a pull request that adds _includes/mermaid.html and one post under _posts/, adds the conditional include to _layouts/default.html, and adds a few lines to style.scss. _config.yml and the other includes and layouts are unchanged. The description pastes the github-pages build output, the <pre><code class="language-mermaid"> line and the single script tag from the built post, and the screenshot of the rendered diagrams.
The run's record holds the gem install, the build, the local server, the browser session and the screenshot, so a reviewer sees the diagram as a visitor would without building the site or trusting a description of a script.
Before merging, a reviewer decides whether to pin Mermaid to the exact version or let the @12 tag float, whether the neutral theme suits the blog's palette, and whether the include should also carry a <noscript> note. Then they add mermaid: true to any existing post with a diagram.
Run it on every post that needs a diagram
Once the include is in, a writer starts a run from the terminal or a script with POST /o/{org}/sessions, the repository in resources, and a prompt that names the post and describes the diagram, and the agent writes the Mermaid source into the post, sets mermaid: true, builds the site and screenshots the result the same way. Send a request_id that is a UUID v5 of the post's path so a retried call returns the run already started.
A team with several Jekyll sites sends one request per repository with this page's prompt instead, and each run reads that site's own layouts and config, so a site that already has a Gemfile and a Mermaid plugin gets a note saying so rather than a second renderer.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Rendering diagrams on GitHub Pages is a short script and a long list of ways to get it wrong: a plugin the build will ignore, a selector written for the wrong HTML, a script that races the page, a module loaded on every page of the site, or a security level loosened without noticing. The agent builds the site with the same gem Pages uses, reads the HTML a fence actually produces, writes the script against that, and then renders it in a real browser in its own sandbox, so the pull request shows the diagram rather than the script.
Every command, the build output, the browser session and the screenshot stay on the run, and nothing is installed on the reader's machine. The same request runs against every Jekyll site a team keeps, each reading its own layout.
Frequently asked questions
Why not a Jekyll Mermaid plugin?
GitHub Pages builds with the github-pages gem and loads only the plugins it bundles; a Mermaid plugin is not one of them, and this repository has no Gemfile to add it to. A plugin would work on a laptop and be silently ignored on Pages, which is the worst outcome. A browser-side render works in both places.
What does a mermaid fence turn into in the built HTML?
Under Jekyll 3.10.0 with kramdown's GFM parser and Rouge, which has no Mermaid lexer, a plain <pre><code class="language-mermaid"> with the diagram source escaped inside. The script reads that text content back, which undoes the escaping, and hands it to Mermaid. The agent confirms this from the build rather than assuming it.
Does every page load Mermaid?
No. The include sits inside {% if page.mermaid %} in default.html, so only a post with mermaid: true in its front matter fetches the module. The agent checks the built index and a post without the flag for any reference to the script and quotes the result.
Why pin the version in the import?
So the diagrams render the same next year. mermaid@12 would float to every 12.x release; mermaid@12.3.0 is the exact build the agent rendered and screenshotted. A reviewer who prefers to track the major changes one character in the include.
Is it safe to render user-supplied diagram text?
The diagrams are the blog's own posts, and Mermaid runs at its default securityLevel of strict, which encodes HTML in labels and disables click handlers. The agent does not loosen it; a post that needs links in a diagram is a decision for the reviewer.
More Jekyll jobs
The same job on other stacks
- Add Mermaid Diagrams to an mdBook (mdBook)
- Add Mermaid Diagrams to a MkDocs Site (MkDocs)
- Add Mermaid Diagrams to Sphinx Docs (Sphinx)