Add Diagrams to your Jekyll/Hugo/Gatsby blog with Mermaid JS
Add diagrams to your JAMStack (Jekyll/Hugo/Gatsby) blog with Mermaid JS
The following post will go through how to integrate Mermaid JS, a “simple markdown-like language for generating charts”.
It will initially go through the benefits of MermaidJS, followed by a generic (cross-technology) integration, finally it will tackle the Hugo-way of dealing with this issue.
Table of Contents
Why MermaidJS?
Mermaid is a “a simple markdown-like script[ing] language for generating charts from text via javascript”, it fits very well within a text-driven workflow on top of the JAMStack.
This is because Markdown is one of the top options of the M (Markdown) component of JAMStack, so it makes sense to add a “markdown-like” language to create diagrams within your Hugo/Gatsby/Hexo/Jekyll posts.
Mermaid allows you to defined charts using text like the following:
graph LR;
A-->B;
Which looks like the following (see it here if you have JS disabled):
The simplest/most generic MermaidJS integration
No Hugo required, this approach will work for any site where you can edit the posts as HTML/Markdown (where HTML
div
-s are allowed) and you can add<script>
tags
This is the simplest integration:
<div class="mermaid">
graph LR;
A-->B;
</div>
<script async src="https://unpkg.com/[email protected]/dist/mermaid.min.js"></script>
Feel free to include the script tag anywhere on the page, it’s marked as async
so should not render blocking regardless. For more information about async
, see the script
tag MDN documentation
We’re leveraging unpkg.com, “a fast, global content delivery network for everything on npm”.
Unfortunately for users of Hugo, this breaks out of the Hugo paradigm since it just injects HTML into pages.
Integrating MermaidJS as a Hugo shortcode
What is a Hugo shortcode?
Often, content authors are forced to add raw HTML (e.g., video
<iframes>
) to Markdown content. We think this contradicts the beautiful simplicity of Markdown’s syntax.Hugo created shortcodes to circumvent these limitations.
A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files.
In other words: shortcodes are ways to abstract functionality that you would interact with in your content (Markdown) files.
Usage example would be with the tweet
built-in shortcode example from the Hugo docs:
{{< tweet 1160591925222748162 >}}
Which renders as:
You can escape @GoHugoIO shortcode syntax using /* */ eg.
— Hugo (@hugo__df) August 11, 2019
{{</* tweet tweet-id */>}}
Shortcodes with a body using .Inner
Add the following shortcode to layouts/shortcodes/mermaid.html
:
<div class="mermaid">
{{.Inner}}
</div>
By using .Inner
, our shortcode can be used as follows:
{{<mermaid>}}
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
{{</mermaid>}}
Which is handier than the alternative which is passing parameters into the shortcode in a way akin to React/Vue/Angular props or HTML attributes (see the tweet example earlier in the post).
Loading the MermaidJS script only on pages that need it
Add the following conditionals around the script:
{{ if (.Params.mermaid) }}
<!-- MermaidJS support -->
<script async src="https://unpkg.com/[email protected]/dist/mermaid.min.js"></script>
{{ end }}
This is will make sure that mermaid.min.js
does not get loaded unless the post specifically says that it needs it.
In your post (or other) frontmatter:
mermaid: true
In your post content you can now write Mermaid diagrams:
{{<mermaid>}}
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
{{</mermaid>}}
Make sure to switch on
mermaid: true
otherwise you’ll just see the following textgraph TD; A-->B; A-->C; B-->D; C-->D;
See the diagram in action:
If you have JS disabled you’ll just see text but you can see a picture of the diagram in action.
That’s it, MermaidJS, why it’s cool, how easy it is to integrate and how to do so as a Hugo shortcode.
Get The Jest Handbook (100 pages)
Take your JavaScript testing to the next level by learning the ins and outs of Jest, the top JavaScript testing library.
orJoin 1000s of developers learning about Enterprise-grade Node.js & JavaScript