How to write workflow diagrams in markdown using mermaid.js and hugo shortcodes

Mermaid.js is a code based diagram tool that is very easy to setup and use and can be embedded in a website or blog. I had it up and running in just a few minutes.

How to setup mermaid.js using a hugo shortcode

Step 1: create a shortcode for the mermaid.js html wrapper

A hugo snippet makes it quick and easy to add mermaid.js diagrams directly to markdown files, without typing html. Create a file in layouts/shortcodes named mermaid.html, then add this to it:

<div class="mermaid">
{{ .Inner }}
</div>

Step 2: configure layout to load mermaid.js script where applicable

Add this to the head.html partial, or whichever template or layout is generating your document head if you have it configured differently:

{{ if .Params.useMermaid }}
    <!-- Load mermaid.js when "useMermaid = true" set in content front matter -->
    <script async src="https://unpkg.com/mermaid@8.4.4/dist/mermaid.min.js"></script>
{{ end }}

This will check if the useMermaid parameter in the markdown file front matter is set to true before loading the mermaid.js script. You can set the default of useMermaid to true or false, depending on your use case.

I went with false, so it will only load when explicitly requested.

Step 3: add a useMermaid parameter to the appropriate archetype

Archetypes are what automatically add front matter to content when you type ‘hugo new post/my-new-post.md’. Adding the useMermaid parameter to the archetype adds visibility. Setting it to false by default prevents bloat.

Add this to the appropriate archetype (in my case themes/my-theme-name/archetypes/default.md):

<!-- Set as true for content with mermaid.js diagrams -->
useMermaid: false

Step 4: make sure everything is configured correctly

Create a new file using hugo on the command line, for me it looks something like this:

C:\repos>hugo new notes/mermaidtest.md

Open the file and change the front matter parameter useMermaid to true:

---
title: "How to use mermaid.js for diagrams in hugo"
date: 2020-05-25T17:10:23-05:00
useMermaid: true
---

(Front matter simplified for clarity, actual front matter contains close to a dozen parameters.)

Then insert the mermaid.html shortcode somewhere in the main content:

<!-- Remove the /* and */ from each tag -->
{{/*<mermaid>*/}}
    graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
{{/*/<mermaid>}}

Note: remove the /* and */ from each tag. Those are there to get the markdown renderer to display the shortcode tags on this webpage.

Now start the hugo server:

C:\repos>hugo server

Open up the test page in a browser and see if this is there:

If you see that it worked.

Otherwise, good luck!

How to use mermaid.js with hugo, multiple examples

Create a flowchart diagram with different lines and nodes

Type this inside a mermaid shortcode:

graph TD;
  A(Start here) --> | add text? | B(Rounded)
  A -.-> C{Choose?}
  A ==> D[This one]
  A --- E((Circle))
  C -.-> F(The end)
  C --> G[Keep going]
  F --> G

Get this:

Looking for more? Here’s a link to the flowchart page of the mermaid.js docs.

How to display a basic GANTT chart using mermaid.js in a hugo blog

Type this inside the mermaid shortcode tags:

gantt
dateFormat YYYY-MM-DD
title Mermaid GANTT chart diagram
excludes weekdays 2020-05-25

section A section
Completed task :done, des1, 2020-05-20, 2020-05-30
Active task: active, des2, 2020-05-29, 7d
Future task:         des3, after des2, 5d
Future task2:        des4, after des3, 3d

Get this: