Rendering Mermaid Diagrams on a Hugo Website Using Quarto

Setting up Hugo to Support Mermaid

Steps for setting up Hugo to support Mermaid are detailed in the Hugo documentation, however that didn’t seem to work for me (producing errors when Netlify tries to publish the site). Instead, I had to take a slightly different approach, which was inspired by Kevin Wu’s blog post about using Mermaid with Hugo. This should work for others, but if it doesn’t, please lets just assume that it is either Kevin’s fault, or your fault, but definitely not my fault.

First, create a HTML file /layours/partials/mermaid.html, and add the following code, which specifies where to find Mermaid and how it should be loaded (in this case I’ve specified the dark theme, but there’s a few different options):

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

Following this, a snippet needs to be added to one of the partial layouts that will be used in your content pages. I added it to the extend_head.html file (which, as the name helpfully suggests, is just an extension of head.html). This snippet just tells Hugo that, when Mermaid is called in the frontmatter, it needs to use the mermaid.html partial you just created.

{{ if .Page.Params.mermaid }}
{{ partial "mermaid.html" . }}
{{ end }}

This can either be added to the existing theme partial, located in themes/<theme-name>/layouts/partials, or it can be in the global layouts/partials directory, which will override your theme.

Now, you just have to add mermaid: true to the YAML frontmatter for any page that contains a Mermaid code block, and you’re good to go!

Rendering Mermaid Using Quarto

Once you’ve set Hugo up to handle Mermaid code blocks, you would think it should then render like other code chunks in Quarto, and you would be right. Mermaid is very good.

I find that I sometimes have to render the Quarto document a couple times for Mermaid diagrams to show up, or for changes to render properly, but that’s about the only issue that I’ve come up against.

```{mermaid}
%%| label: fig-mermaid-flowchart
%%| fig-cap: Wow look how it flows.
%%| fig-alt: An example flowchart, drawn using Mermaid.

graph LR
    A([Oooh]) --> B([Would You])
    B --> C([Look at This])
    C --> D[Very]
    C --> E[Fancy]
    C --> F[Flowchart]
```

graph LR
    A([Oooh]) --> B([Would You])
    B --> C([Look at This])
    C --> D[Very]
    C --> E[Fancy]
    C --> F[Flowchart]

```{mermaid}
%%| label: fig-mermaid-gantt
%%| fig-cap: Oh you real fancy huh?
%%| fig-alt: An example Gantt chart, drawn using Mermaid.

%%{init: {'theme': 'default', 'themeVariables': { 'textColor': '#798189'}}}%%
gantt
    title Big Ol' Gantts
    dateFormat  YYYY-MM-DD
    section Section
    Some Normal Tasks : done, a1, 2022-09-01, 15d
    But Wait, There's More! :after a1, 20d
    section And ANOTHER
    Deary Me, It's Never Ending : crit, 2022-10-01, 20d
    I Hate This Project : 14d
```

%%{init: {'theme': 'default', 'themeVariables': { 'textColor': '#798189'}}}%%
gantt
    title Big Ol' Gantts
    dateFormat  YYYY-MM-DD
    section Section
    Some Normal Tasks : done, a1, 2022-09-01, 15d
    But Wait, There's More! :after a1, 20d
    section And ANOTHER
    Deary Me, It's Never Ending : crit, 2022-10-01, 20d
    I Hate This Project : 14d

```{mermaid}
%%| label: fig-mermaid-git
%%| fig-cap: Git a load of this!
%%| fig-alt: An example Git graph, drawn using Mermaid.

gitGraph
  commit
  commit
  branch develop
  checkout develop
  commit
  commit
  checkout main
  merge develop
  commit
  commit
```

gitGraph
  commit
  commit
  branch develop
  checkout develop
  commit
  commit
  checkout main
  merge develop
  commit
  commit

Summary

And that’s about all you need to do. Think of all the amazing diagrams you’re going to create and show the world? I, on the other hand, am going to continue to make minimal diagrams that are completely uninspiring. Have fun!