Markdown is a pretty nice tool for developers to write documents. But it doesn’t support creating graphs & charts easily. Mermaid is a powerful js library which can convert a text described graph or chart and render it. It’s a perfect tool when using with Octopress (A bloging tool based on Jekyll). Here I’ll show you how to integrate the mermaid with minimal effort into your Octopress (or Jekyll) website.

For the purposes of this tutorial - I will be be using Octopress, but this should be fairly trivial to also add this to your Jekyll template.

Integrating mermaid.js directly

While there is a Jekyll Mermaid plugin available, it is much more complicated to setup and use. We will be using the mermaid CDN directly. Lets get started.

In your Octopress blog directory, navigate to the source/_includes/head.html file and add the following anywhere between the tags. If you are using Jekyll, just add it to where ever your header tags are defined (usually in _layouts/default.html).

1
2

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>

Since Markdown is pretty friendly to html tags, you can simply add a diagram by wrapping mermaid markup in a div with class “mermaid” for example:

1
2
3
4
5
6
7

<div class="mermaid">
graph LR
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]
</div>

Which when rendered outputs:

You can try out your code before deployment using a live editor. Mermaid documentation can be found here.

Thats it! If you have any questions feel free to get in touch or leave a comment.