Diagrams with Mermaid

October 29, 2023 3 minutes reading time Development javascript

Mermaid is a tool with a syntax inspired by Markdown that allows you to generate diagrams using text descriptions. With Mermaid, you can generate Flow charts, UML diagrams, Pie charts, Gantt diagrams, Entity Relationship diagrams, and more.

An Entity Relationship diagram example

    
%%{ init: {'theme': 'forest'} }%%
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINEITEM : contains
    PRODUCT ||--o{ LINEITEM : is_listed_in
    CUSTOMER {
        string Name
        string Email
        string Address
    }
    PRODUCT {
        string ProductName
        float Price
    }
    ORDER {
        date DateOrdered
        string Status
    }
    LINEITEM {
        int Quantity
    }

Using Mermaid in your blog post

For your Hugo-powered blog, a diagram shortcode allows you to easily embed Mermaid diagrams in your posts. The shortcode is defined in the file layouts/shortcodes/diagram.html of your theme:

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

For this to work properly, the Mermaid JavaScript library needs to be loaded. This is done in the file layouts/partials/head.html of your theme – or in another file that is included in the head section of your blog posts:

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

Note: The diagrams will only be visible on the live site and not in the markdown file.

Basic Usage

To use the shortcode in your blog post, you would use the following format:

{{< diagram >}}
Your Mermaid diagram code here
{{< / diagram >}}

Replace Your Mermaid diagram code here with your actual Mermaid diagram code.

To load the necessary JavaScript to render the Mermaid diagram, you need to enable it in the front matter of your blog post by setting the value for diagram to true:

---
diagram: true
---

Configuring the Appearance

The shortcode allows you to specify configuration options for Mermaid, particularly changing the appearance of the diagrams through the theme.

For example, to apply the forest theme:

{{< diagram >}}
%%{ init: {'theme': 'forest'} }%%
Your Mermaid diagram code here
{{< / diagram >}}

Providing init Configuration

When using the init configuration, see here for reference.

Here’s a more advanced example with multiple configuration options:

{{< diagram >}}
%%{ init: {'theme': 'forest', 'themeVariables': {'primaryColor': '#FF0000'}} }%%
Your Mermaid diagram code here
{{< / diagram >}}

In this example, we’re using the forest theme and changing the primary color to red (#FF0000).

Putting it all together

Use the shortcode by enclosing your Mermaid diagram code with {{< diagram >}} ... {{< / diagram >}}. To change the look of the Mermaid theme, provide values for the init parameter. With this shortcode in place, integrating and customizing Mermaid diagrams in your blog posts becomes a breeze!

Explaining Mermaid diagram code in a post

Here is how the diagram rendered above is embedded in this blog post as a code block. Because it is the same code as the diagram above, extra care has to be taken to prevent Mermaid from rendering it as a diagram.

{{< diagram >}}
%%{ init: {'theme': 'forest'} }%%
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINEITEM : contains
    PRODUCT ||--o{ LINEITEM : is_listed_in
    CUSTOMER {
        string Name
        string Email
        string Address
    }
    PRODUCT {
        string ProductName
        float Price
    }
    ORDER {
        date DateOrdered
        string Status
    }
    LINEITEM {
        int Quantity
    }
{{< / diagram >}}

If you want to mention it in your Hugo-powered blog post, make sure to mark it as a block-comment (/* and */) after the opening less-than sign and before the closing greater-than sign in your diagram shortcode to prevent Mermaid from rendering it:

{{</* diagram >}}
Your Mermaid diagram code here
{{< / diagram */>}}