Skip to content

Conversation

@miklz
Copy link

@miklz miklz commented Oct 6, 2025

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]
Loading

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.

This commit introduces native Mermaid diagram rendering to the theme.

Following Hugo’s official documentation, a new custom code block renderer
(`render-codeblock-mermaid.html`) was added under `layouts/_default/` to
detect Mermaid code blocks and inject the necessary script flag into the
page context.

Additionally, the `baseof.html` template now conditionally includes the
Mermaid JS module from the CDN when a page contains a Mermaid diagram:

  {{ 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 }}

This enables rendering of fenced code blocks using the `mermaid` language
in markdown files without requiring any external preprocessing.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant