hugo-theme-stack icon indicating copy to clipboard operation
hugo-theme-stack copied to clipboard

Add support for Mermaid diagrams in markdown content

Open miklz opened this issue 3 months ago • 0 comments

Add Mermaid Diagram Support to the Theme

This PR adds native Mermaid diagram rendering support to markdown content. It allows users to include diagrams directly in code fences, e.g.:

graph TD
  A[Start] --> B{Is it working?}
  B -->|Yes| C[Ship it!]
  B -->|No| D[Fix it]

Implementation Details

  • Added a new custom renderer: layouts/_default/render-codeblock-mermaid.html This file wraps Mermaid code blocks in a <pre class="mermaid"> tag and sets a flag (hasMermaid) on the page context.

  • Updated baseof.html to conditionally include the Mermaid JavaScript module from the CDN only when needed:

{{ if .Store.Get "hasMermaid" }}
  <script type="module">
    import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
    mermaid.initialize({
      startOnLoad: true,
      theme: 'neutral',
    });
  </script>
{{ end }}

Benefits

  • No external preprocessing or shortcodes required.
  • Lightweight and only loaded when a page actually includes Mermaid diagrams.
  • Works seamlessly with existing markdown content and Hugo’s markup system.

miklz avatar Oct 06 '25 10:10 miklz