To add Mermaid support to Hugo, one key detail not explicitly covered in the official documentation is that code fences must be used to enable rendering hooks for code blocks. If code fences are not enabled, the rendering hook has no effect.

Additionally, the condition for including Mermaid.js does not function as expected. Despite trying multiple approaches, I was unable to make it work reliably and ultimately decided to remove the conditional statement entirely.

complete configuration

hugo.toml

[markup]
[markup.highlight]
codeFences = true # enable render code block hook
noClasses = false # tells Hugo to use CSS classes instead of inline styles

layouts/_default/_markup/render-codeblock-mermaid.html

<pre class="mermaid">
  {{- .Inner | safeHTML }}
</pre>
<script type="module">
  import mermaid from '[](https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';)
  mermaid.initialize({ startOnLoad: true }); 
</script>