Recently, I have taken a strong interest in Diagrams as Code and specifically, I have been looking at Mermaid, Structurizr and C4 models. I want to be able to include some diagrams in this blog but wanted to do it without using extra gems. This post explains how to do it if you’re writing pages for Jekyll using Textile markup.

I started by looking up instructions on how to get it to work. I found this page by Jack Gruber but ran into two main problems:

• The second code piece in the example is a duplicate of the first and is therefore, not correct
• That sample works with Markdown and not with Textile markup (which is what I prefer to use)

Setting it up

What we need to do:

• Load the Javascript for Mermaid from our page → we do this into the layout for our posts
• Initialise Mermaid once the page is loaded

The code for this needs to be included into the layout and the simple way to add this is to put the following piece of code into the footer for your theme.

1
2
3
4
5
6
7
8
9
10
<script src="https://unpkg.com/mermaid/dist/mermaid.min.js"></script>
<script>
  $(document).ready(function () {
    mermaid.initialize({
      startOnLoad:true,
      theme: "default",
    });
    window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));
  });
</script>

This will do both the things that are needed to load and initialise Mermaid in our page.

Add diagram code

The next thing we need is:

• We need to add Mermaid code into our page so that the Mermaid code can find it and render it

You may have noticed that in the window.mermaid.init we ask it to find blocks that have the class language-mermaid and these are the ones that get rendered as diagrams. These blocks are produced when we include a code sample (like the Javascript code above). When using markdown, we do this by starting a line with ```mermaid so that it indicates to the markdown renderer that we are rendering a code sample for mermaid.

In Textile, in the current setup, a code sample is included using {% highlight language} and so we include {% highlight mermaid %} for mermaid. When the page is rendered, these blocks are picked up and rendered by Mermaid as diagrams. The sample below shows one of the simplest Mermaid diagrams.

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

In case you’re wondering, this works also if you have multiple diagrams in your page as you see another one below.

sequenceDiagram
    participant Alice
    participant John
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!
    John->>John: Note changes

Not including Mermaid for every page

The mermaid Javascript is quite large and it does not make sense to include it for every page. It should only be included if the page actually has any diagrams. For this, we:

• Include a flag in the front matter of the post. If we include mermaid: true in the front matter at the top of the page, we indicate to Jekyll that this page will use mermaid and the Javascript should be included and initialised.
• We add a condition in the footer to include the code above only if the flag is set.

For this we wrap the code above in a condition in the footer file.

{% if page.mermaid }
… the rest of the Javascript code from above …
{ endif %}

This completes this short post on how to use Mermaid in a Textile post using Jekyll. This is mainly written for me to remember what I need to do; if it helps someone, that’s great. Of course, feel free to share the post (you can tag me as @onghu on Twitter or on Mastodon as @onghu@ruby.social ) or leave a comment below.