What happened?

I had a custom mermaid integration for my blog that also used mermaidjs, but used shortcodes instead of code blocks and the below worked fine with that implementation:

{{< mermaid >}}
flowchart TD
    subgraph client["👤 Client Device"]
        A["MacBook with WARP Client<br/>100.96.0.5"]
    end

    subgraph cloudflare["☁️ Cloudflare Network"]
        B["Cloudflare Edge<br/>(Zero Trust Gateway)"]
    end

    subgraph nas["🖥️ NAS - Docker Host (172.31.4.0/24)"]
        C["warp-connector<br/>100.96.0.4"]
        D["CoreDNS<br/>172.31.4.53"]
        E["Traefik<br/>172.31.4.100"]
        F["Internal Services<br/>(sonarr, radarr, etc.)"]
    end

    A -- "WARP Tunnel<br/>(encrypted)" --> B
    B -- "WARP Tunnel<br/>(encrypted)" --> C
    C -- "DNS Query" --> D
    D -- "Resolved IP" --> C
    C -- "HTTP Request" --> E
    E --> F

    style client fill:#1a365d,stroke:#2c5282,color:#fff
    style cloudflare fill:#f6ad55,stroke:#dd6b20,color:#000
    style nas fill:#276749,stroke:#22543d,color:#fff
{{< /mermaid >}}

This is valid mermaidjs code according to Mermaid.live.

Now that the upstream supports mermaid from #1186, I wanted to try and give it a shot. So I removed my custom integrations for it and built the site again.

But if I remove the {{< mermaid >}} shortcode and replace it with

```mermaid
```

This doesn't generate a mermaid diagram / flow chart, and I just get syntax errors. I assume because of the
and style lines at the bottom.

I also noticed that with partialCached, I can't get this to work at all, and it just outputs code blocks, but if I switch this to partial then it begins to work properly.

I replicated the issue here, using the codeblock, and nothing gets populated.

```mermaid 
```

The file content specifically.

There a few race conditions here that need to be fixed mainly, but once the actual JS code gets loaded, then you end up with:

Console error:

{
  "message": "No diagram type detected matching given configuration for text: ",
  "hash": "UnknownDiagramError"
}

I don't mind making a PR on this to try and have it more extensively support mermaid for all of the use cases.

After plugging this into claude to play around and find the root cause, it came up with this:

Issue: Mermaid diagrams fail to render with upstream theme implementation

Environment

• Hugo Theme Stack: v3.33.0
• Hugo: v0.152.2
• Mermaid.js: v11.x (via ESM import from cdn.jsdelivr.net)

Problem

When using the upstream theme's mermaid code fence syntax, diagrams fail to render with the following error:

Visual error:

Syntax error in text
mermaid version 11.12.2

Console error:

{
  "message": "No diagram type detected matching given configuration for text: ",
  "hash": "UnknownDiagramError"
}

Example Diagram That Fails

```mermaid
flowchart TD
    subgraph client["Client Device"]
        A["MacBook with WARP Client<br/>100.96.0.5"]
    end

    A -- "WARP Tunnel<br/>(encrypted)" --> B

    style client fill:#1a365d,stroke:#2c5282,color:#fff
```

Root Causes Identified

1. partialCached breaks .Store detection

File: layouts/_default/single.html

The upstream uses:

{{ partialCached "article/components/mermaid" . }}

This caches globally, preventing per-page .Store.Get "hasMermaid" from working correctly. The first page processed (without mermaid) caches an empty result.

Fix: Use partial instead of partialCached:

{{ partial "article/components/mermaid" . }}

2. htmlEscape breaks <br/> tags

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

The upstream uses:

{{ .Inner | htmlEscape | safeHTML }}

This escapes <br/> to <br/>, breaking HTML labels in diagrams.

<br/> is a supported method in MermaidJS

Fix: Remove htmlEscape:

{{ .Inner | safeHTML }}

3. ES module timing issue with startOnLoad

File: layouts/partials/article/components/mermaid.html

With ES modules (which are deferred), by the time mermaid.initialize() runs with startOnLoad: true, the DOMContentLoaded event has already fired.

Fix: Use startOnLoad: false and explicitly call mermaid.run():

mermaid.initialize({
    startOnLoad: false,
    // ... config
});
await mermaid.run();

4. Missing mermaid configuration options

File: layouts/partials/article/components/mermaid.html

The upstream uses:

mermaid.initialize({
    startOnLoad: true,
    theme: 'neutral',
});

Missing securityLevel: 'loose' and htmlLabels: true, which are required for <br/> tags in labels.

Fix:

mermaid.initialize({
    startOnLoad: false,
    theme: getTheme(), // for dark/light mode support
    securityLevel: 'loose',
    flowchart: {
        useMaxWidth: true,
        htmlLabels: true
    }
});

I can create a PR that manages to fix this or at the very least, make it entirely module so we have safe implementations by default, but can disable those implementations to allow for this otherwise.

Hugo version

hugo v0.152.2+extended+withdeploy darwin/arm64 BuildDate=2025-10-24T15:31:49Z VendorInfo=brew

Theme version

3.33.0

What browsers are you seeing the problem on?

Chrome

More information about the browser

macOS 26, Chrome 143.0.7499.148

Relevant log output

Console Output:


{
    "str": "No diagram type detected matching given configuration for text: ",
    "message": "No diagram type detected matching given configuration for text: ",
    "hash": "UnknownDiagramError",
    "error": {
        "name": "UnknownDiagramError"
    }
}

Link to Minimal Reproducible Example

https://github.com/delize/hugo-theme-stack-starter/tree/pr1186-issues