# Add Mermaid Diagrams to a Jekyll Blog on GitHub Pages

Yes. An agent makes mermaid code fences render as diagrams on a GitHub Pages blog with one include and no plugin, loads it only on posts that opt in, and opens a PR.

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

## 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`

```json
{
  "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"
    }
  ]
}
```

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

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.

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

- [Add Open Graph and Twitter Card Tags to a Jekyll Blog on GitHub Pages](https://getrush.ai/run/add-open-graph-tags/jekyll/)
- [Add Pagination to a Jekyll Blog](https://getrush.ai/run/add-pagination/jekyll/)
- [Add Reading Time to a Jekyll Blog](https://getrush.ai/run/add-reading-time/jekyll/)

## The same job on other stacks

- [Add Mermaid Diagrams to an mdBook](https://getrush.ai/run/add-mermaid-diagrams/mdbook/)
- [Add Mermaid Diagrams to a MkDocs Site](https://getrush.ai/run/add-mermaid-diagrams/mkdocs/)
- [Add Mermaid Diagrams to Sphinx Docs](https://getrush.ai/run/add-mermaid-diagrams/sphinx/)

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