Mermaid Diagramming in Jekyll in 2025

This blog is built with Jekyll. I have been using Mermaid Diagrams in documentation at work. I find Mermaid to be a quick and easy way for me to add visual information to a document. If you are not familiar, Mermaid uses “Markdown-inspired text definitions to create […] diagrams dynamically.”

The syntax is easy to learn. For example, this text:

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

Generates this diagram:

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

The diagrams can be quite complex:

classDiagram
Class01 <|-- AveryLongClass : Cool
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 --> C2 : Where am i?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 <--> C2: Cool label

classDiagram
Class01 <|-- AveryLongClass : Cool
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 --> C2 : Where am i?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 <--> C2: Cool label

Lacking strong graphic design skills, I find I can produce diagrams much more quickly with Mermaid, especially if I ask an LLM for help (but that’s a different blog post).

Jekyll and Mermaid

Mermaid is a JavaScript library. When initialized, it looks for a mermaid class in the document, typically on a <pre> or <div> tag. It then parses the text inside the tag and renders the diagram, replacing the tag’s content with an SVG.

Out of the box, Jekyll does not support Mermaid. There have been a few Jekyll plugins that add support for Mermaid, but none are currently maintained. There are also several blog posts on how to add Mermaid to Jekyll; however, these tutorials are for older versions of Mermaid and do not work with the current version. So, here’s how to do it in 2025 with Mermaid 11.

Adding Mermaid to Jekyll

These instructions are for the default Jekyll theme, Minima. If you are using a different theme, you may need to make adjustments.

Create a new file in the _includes directory (create the directory if it doesn’t already exist) and name it mermaid.html. This file will contain the Mermaid JavaScript:

<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<script>
  document.addEventListener('DOMContentLoaded', function() {
    mermaid.initialize({startOnLoad:true});
    await mermaid.run({
      querySelector: '.language-mermaid',
    });
  });
</script>

The important part is the querySelector: '.language-mermaid'. By default, Mermaid looks for a mermaid class, but Jekyll, when using a code block with a language tag, adds a language- prefix to the class. This tells Mermaid to look for the language-mermaid class instead.

Next, add the following to the head.html file in the _includes directory, creating the file if it doesn’t already

 <script type="module">
 import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
 mermaid.initialize({ startOnLoad: true });
 await mermaid.run({
     querySelector: '.language-mermaid',
 });
</script>
 

This will include the Mermaid JavaScript only if the mermaid variable is set to true in the front matter of the page.

Finally, add the mermaid variable to the front matter of the page where you want to include a Mermaid diagram:

---
layout: single
title: "Mermaid Diagramming in Jekyll in 2025"
mermaid: true
---

Now any code block with the language set to mermaid will be rendered as a diagram. For example:

```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```

And that’s it! You can now add Mermaid diagrams to your Jekyll blog.