Integrating Mermaid Diagrams into Your Hugo Site

Mermaid is a powerful JavaScript-based diagramming and charting tool that lets you create diagrams using text and code, making them version-controllable and maintainable. By integrating Mermaid with your Hugo site, you can create flowcharts, sequence diagrams, class diagrams, and more, all within your Markdown content.

Why Use Mermaid with Hugo?

  • Simple Syntax: Create diagrams using an easy-to-learn markdown-like syntax
  • Maintainable: Store diagrams as text, making them version-controllable
  • Dynamic: Diagrams render in the browser, enabling interactive features
  • Adaptable: Your diagrams will automatically match your site’s theme

Let’s walk through the steps to add Mermaid support to your Hugo site.

Step 1: Add the Mermaid JavaScript Library

First, you’ll need to include the Mermaid library in your Hugo site. Create a custom layout partial to load the script:

  1. Create a file named mermaid.html in your site’s layouts/partials/ directory:
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>
  document.addEventListener('DOMContentLoaded', function () {
    mermaid.initialize({
      startOnLoad: true,
      theme: 'default',
      securityLevel: 'loose',
      flowchart: { useMaxWidth: false, htmlLabels: true }
    });
  });
</script>
  1. Include this partial in your site’s footer or header template. For example, in layouts/partials/footer.html:
{{ partial "mermaid.html" . }}

Step 2: Enable Raw HTML in Markdown

By default, Hugo escapes raw HTML for security purposes. To allow raw HTML (which Mermaid requires), you need to update your site configuration.

  1. Open your Hugo configuration file (config.toml, config.yaml, or config.json).

  2. Add or update the following settings:

    For config.toml:

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

    For config.yaml:

    markup:
  goldmark:
    renderer:
      unsafe: true

This enables Hugo to process raw HTML embedded within your Markdown files.

Step 3: Create Your First Mermaid Diagram

Now you can add Mermaid diagrams to your Markdown content. Here’s an example of a simple flowchart:

flowchart LR
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B

Step 4: Style and Test

  1. Test Locally: Run your Hugo development server to test the setup:

    hugo server

    Open your site at http://localhost:1313 to ensure that the Mermaid diagrams render as expected.

  2. Add Custom Styles (Optional): You can adjust the appearance of Mermaid graphs by adding custom CSS rules to your assets/css/style.css file (or equivalent).

    Example:

    .mermaid {
    margin: 20px 0;
}

Step 5: Create a Shortcode for Mermaid

To simplify adding Mermaid diagrams, create a Hugo shortcode:

  1. Create a file named mermaid.html in your layouts/shortcodes/ directory:
<pre class="mermaid">
  {{- .Inner -}}
</pre>
  1. Use the shortcode in your Markdown files:
    graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

This approach makes embedding Mermaid diagrams simpler and ensures consistency across your site.

Conclusion

By integrating Mermaid.js, you can enhance your Hugo site with dynamic and visually appealing graphs directly within your Markdown content. Whether you’re creating flowcharts, sequence diagrams, or entity-relationship diagrams, Mermaid makes it easy to deliver engaging visuals.

Related Posts