Right, so you want to draw diagrams. You’ve tried pasting screenshots from some clunky web app into your blog post and it’s a nightmare. The text is blurry, the colors are wrong, and heaven forbid you need to update it later. You’re a developer, not a graphic designer. Your tools should work for you.

This is where Mermaid swoops in like a superhero in a terribly drawn cape. It’s a JavaScript-based diagramming tool that lets you create everything from flowcharts to sequence diagrams using nothing but text. It’s code, for pictures. And Hugo, being the opinionated genius it is, has first-class support for it through its default Markdown renderer, Goldmark.

How Hugo and Mermaid Hold Hands

Here’s the beautiful part: you don’t need to install a separate plugin or wrestle with configuration. If you’re using a recent version of Hugo (and you really should be), Goldmark is configured to handle Mermaid code blocks out of the box. Well, almost. The engine is there, but it’s sleeping by default. You need to wake it up in your site’s configuration.

You do this by telling Hugo’s Markup settings to enable it. Crack open your hugo.toml (or config.toml if you’re clinging to the past like a digital raccoon) and add this:

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      mermaid = true
  [markup.goldmark.renderer]
    unsafe = true

The unsafe = true part is, frankly, a bit of a misnomer. It sounds like you’re about to deploy a vulnerable site. In reality, it just allows Goldmark to render raw HTML and potentially dangerous links, which the Mermaid integration needs to work its magic. It’s safe in this context. Probably. (I’m kidding, it’s fine).

Your First (Mermaid) Flowchart

Now for the fun bit. In your Markdown file, you simply create a code block and label it as mermaid. The Hugo build process will see this, and instead of just shoving it into a <pre><code> tag, it will transform it into a <div class="mermaid">. Then, it’s the job of the Mermaid JavaScript library to find that div and render the diagram client-side in the reader’s browser.

Let’s create a brutally honest flowchart about writing a blog post:

```mermaid
graph LR
    A[Brilliant Idea] --> B[Write Draft]
    B --> C{Is it any good?}
    C -->|Yes| D[Ship it!]
    C -->|No| E[Weep Softly]
    E --> B
```

This will render as a simple flowchart showing the… let’s call it the “iterative” creative process. The syntax is intuitive: graph LR tells Mermaid to make a graph that flows Left to Right. You define nodes with [Text] and connect them with -->.

The Client-Side Reality and The mermaid Shortcode

Here’s the part the manual often glosses over: Hugo doesn’t render the diagram during the static build. It just wraps it up nicely. The actual drawing happens in your user’s browser, powered by the Mermaid JavaScript library. This means you need to include that library on your site.

Many modern themes handle this for you. But if yours doesn’t, or you’re rolling your own, you need to include the script. The official, and frankly easiest, way is to use Hugo’s built-in mermaid shortcode somewhere in your template, like your partial for post footers. It looks like this:

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

The genius of HasShortcode is that it only loads the script on pages that actually use Mermaid, saving bandwidth for everyone else. You can also pass a configuration object to mermaid.initialize() to change themes, adjust fonts, and more. Check their docs for the myriad of options.

Common Pitfalls and How to Avoid Them

  1. The Forgot-to-Enable-It Blunder: You’ve added the config, but the script tag never appears. Double-check your theme’s layout files. If it’s not there, you must add the shortcode snippet yourself. This is the most common trip-up.

  2. The Indentation Tantrum: Mermaid is fiercely sensitive to indentation and newlines, especially for more complex diagrams like sequence diagrams. If your diagram looks wonky, the first thing to do is check your whitespace. A stray space can break the parser. Use a code editor that highlights Mermaid syntax to save your sanity.

  3. The Live-Reload Quirk: When you’re running hugo server, the live reload might not always trigger a re-render of the Mermaid diagram in your browser. You’ll often need to manually refresh the page to see your changes take effect. It’s a minor annoyance, but knowing it saves frustration.

  4. Going Too Big: Mermaid is fantastic, but it’s still rendering in the browser. If you create a massive, incredibly complex diagram with hundreds of nodes, you might start to see performance lag on the client side. For enormous diagrams, you might be better off with a dedicated tool, but for 99% of blog content, Mermaid is perfect.

The best practice? Embrace it for what it is: a fantastic way to keep your diagrams version-controlled, easily editable, and perfectly integrated into your content workflow. It turns a tedious task into a few lines of code. And that’s always a win.