Mermaid + Hugo v2: Better, Faster

It took three days after finishing the work to display Mermaid diagrams (using shortcodes) to discover an easier method. Let’s talk a bit about custom markdown rendering!

I don’t remember the actual search that led me to the unanswered discussion on the PaperMod GitHub page. No, that’s not entirely true. I do remember how I found this. It was in my unclosed tabs as I cleaned up my browser after the initial implementation. What, you don’t have to routinely go back and close a couple (dozen) tabs following the completion of a task? Regardless, this is where you find me, dear reader.

In any case…

Missed Connections

One of the tabs caught my eye, and I read further; maybe I could add something helpful since I just do that same thing (they were trying to display Mermaid in Hugo). Maybe I could get something else useful from the discussion. Oh, here’s that foreshadowing again.

I was interested that they were trying to do the same thing but going at it a different way; they also linked to some sources that I hadn’t found in my first web search foray. And I learned something. It’s relatively easy to write some functionality that uses code fences like the shortcode I was already doing. My ability to remember how to write three backticks is much better than remembering the format and syntax of shortcodes so far.

You Had Me at ```mermaid

Create layouts/_markup/render-codeblock-mermaid.html with this content:

<div class="mermaid">
    {{- .Inner | safeHTML }}
</div>
{{ .Page.Store.Set "hasMermaid" true }}

We lose the justification (more on why that’s ok later). However, the last line is a real nice touch. This ensures that a page variable is set that can be used later to load the mermaid rendering javascript.

With that addition/adjustment, now I only have to put the following text in a markdown file, and it’s loaded just fine. Javascript is loaded as required; no frontmatter adjustments are needed.

```mermaid
graph LR
    A{do you need a panflute?} -->|yes| B[no you don't]
    B --> C[no panflute]
    A -->|no| C
```

And yet…

Ok, so you might want this centered. You could write different markdown renderers and use something like mermaid-left or mermaid-center, but that feels bad, and I believe you might need to feel a little dirty for thinking about it. Just create a shortcode for centering inner content and call it a day. That example isn’t here. I may make that one later. I’m not sure at this point how much I really want/need it, so we’ll see if I get there or not.