Markdown is a pretty nice tools for developers to write the notes or memo. But it doesn’t support the graph natively. Today I will demonstrate how to bring in that function by using mermaid (and manuals). Mermaid is a powerful js library which can convert a text described graph into a real graph when display to readers. It’s a perfect tool when using with Jekyll (a blog tool which translate Markdown to static html page, another powerful tool). In the following article, I’ll show you how to integrate the mermaid with minimal effort into your Jekyll website so that you can enjoy the convenience it brings in.

Jekyll Plugin vs Integrate JS file directly

The best thing Jekyll Mermaid plugin provide is inject the js file on demand (Yes, you still need to download the mermaid js file by yourself or simply config it to a cdn path). If your page doesn’t use the mermaid at all, then the js file won’t be included. Which is a very good feature because the js file is about 1.1 MB. But unfortunately, not build facility support install extra Jekyll plugins like github.io. So I decided to use the js file directly.

Download js files.

Go to the CDN https://unpkg.com/mermaid/ (the official CDN at the time of writing) to choose which version to download. Once you downloaded move the downloaded js file to your Jekyll website’s assets/js/ folder (or any folder you use to store js files).

Use Js file directly

Since Markdown is pretty friendly to cooperate with html tags. So you can simply add following snippets to use it.

<!-- once per markdown file -->
<script src="/assets/scripts/mermaid.min.js"/>

Wherever you need a graph in the page, you can simply add a diagram by wrapping in a div which class is “mermaid” for example:

<div class="mermaid">
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
</div>

which will be rendered as follows

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

How to mimic the plugin behavior

With Jekyll, you could use different layout for every post, so the easiest way to archive the same effect of avoiding downloading unnecessary js files is to create a different layout for the post which uses the mermaid. The layouts are in the _layouts folder. If you didn’t see it, you can create a _layouts folder under your Jekyll site’s root. Then modify the post layout file you want to use. I added following line under the line <article ...> <script src="/assets/js/mermaid.min.js"></script> And in every post I’d like to use the mermaid, I just add use_mermaid = true to the metadata of the post (which is the very beginning of the file with the title stuff).

It is a manual solution but it works. Another more automatically way might be download the Jekyll-mermaid plugin and put the rb file to _plugins folder and require it in the ext.rb which will then essentially using the plugin. I’ll try to come up with script to see is there any way to automatically set the use_mermaid flag in the metadata so that I don’t need to do that manually every time. Will update once I get something.