Mermaid diagrams rendered in GitHub UI not recognising <br> tags

[andygout]

🏷️ Discussion Type

Bug

💬 Feature/Topic Area

Other

Body

When viewing Mermaid diagrams rendered in the GitHub UI (which include excerpts like the below) then I expect it to recognise the <br> tags.

FOOBAR -- 1<br>GET /users/{userId} --> BAZQUX

With the above example, I expect the diagram to be rendered with a line break between "1" and "GET /users/{userId}":

1
GET /users/{userId}

Instead, there was no line break (or even a space), resulting in the content being rendered as a continuous line:

1GET /users/{userId}

The issues does not affect https://mermaid.live, indicating that it is specific to GitHub.

The issue was not present on Fri 07 Aug 2026 but had become present by Mon 10 Aug 2026 (08:32 UTC).

This link https://github.com/mermaid-js/mermaid/blob/develop/docs/syntax/examples.md includes di{Diamond with <br/> line break} but the resultant diagram does not include the line break.

[Codebater]

I couldn't reproduce this on github.com as of today — your exact edge label renders with the line break — so the cause is likely more specific than "GitHub doesn't recognise <br>". I put up a live test file covering the variants so you can see it render directly: https://github.com/Codebater/achievement-lab/blob/main/mermaid-test.md

What I tested (all of these render the break correctly right now):

• <br>, <br/> and <br /> in node labels, quoted and unquoted
• your exact string FOOBAR -- 1<br>GET /users/{userId} --> BAZQUX as an edge label, under both flowchart LR and the legacy graph LR header
• a sequenceDiagram message with <br>
• two different surfaces: file preview and issue comments (Render test: mermaid br in comment context Codebater/achievement-lab#3)

Some background on why this works at all, because it explains your symptom: GitHub renders Mermaid inside a sandboxed iframe with htmlLabels disabled, so the <br> is never rendered as actual HTML. Instead Mermaid itself recognises the tag during label layout and splits the text into separate SVG <tspan> lines. When a sanitizer strips the tag before Mermaid lays out the label (which is what happens under older/stricter configurations), you get exactly what you described: the tag silently disappears and the two halves concatenate into 1GET /users/{userId} with no space.

Given that github.com currently renders it fine, the likely candidates are:

1. GitHub Enterprise Server. GHES bundles an older Mermaid than github.com, and older versions stripped <br> in exactly this way with HTML labels disabled. If you're seeing this on GHES, that's almost certainly the cause — worth adding your GHES version to the report.
2. A stale cached render. The diagram iframes are cached separately from the page; after editing a file the rendered diagram can lag behind the source. A hard refresh rules this out.
3. Escaped source. If the markdown is generated by a tool, check the Raw view — if it literally contains <br> instead of <br>, Mermaid treats it as plain text.

Independent of the cause, there's a workaround that doesn't rely on HTML tags at all — Mermaid "markdown strings" (double quotes + backticks) support literal newlines, and Test 3 in the file above shows it rendering on GitHub:

```mermaid
flowchart LR
  M["`line1
  line2`"] --> N
```

If you can share which surface you're seeing this on (github.com vs Enterprise Server, and file preview / README / wiki / gist), that should narrow it down quickly.

[andygout]

Thanks @Codebater

For your examples (https://github.com/Codebater/achievement-lab/blob/main/mermaid-test.md and Codebater/achievement-lab#3) the line breaks appear correctly, though I'm still seeing the issue on github.com for all the rendered Mermaid diagrams that use <br> in https://github.com/mermaid-js/mermaid/blob/develop/docs/syntax/examples.md.

[Codebater]

Great pointer — that let me corner it properly. You're right, and I can now reproduce the difference: the same bytes render differently depending on which page they're on. I copied examples.md verbatim into my test repo (repro-full.md) — there, every <br> works, including the sequence note and the diamond. On the mermaid docs page, the same note renders as one endless line. Same content, same browser, minutes apart.

So I diffed what the two pages actually ship. GitHub doesn't render mermaid server-side — the page HTML carries the diagram source in a data-json attribute (on the js-render-enrichment-target div) and the client posts it into the viewscreen iframe. That attribute is where the two pages differ:

• broken docs page: the embedded source contains a literal <br/>
• my freshly-rendered copy: the same spot holds the entity-escaped form <br/>

The current renderer sanitizes raw HTML tags out of label text (tags get deleted, not displayed — which is exactly why you get 1GET with not even a space left behind), but it recognizes the escaped <br/> form and turns it into a line break.

Why would two pages embed differently? The rendered-markdown HTML is cached per blob. examples.md hasn't been touched in about two years, so its cached HTML still carries the old escaping behavior from whenever it was generated — and that old embedding now feeds raw <br/> into a renderer that has since become stricter. Fresh renders get the new escaping and work. I also checked the same file on the master branch: identical broken embedding, which fits — both refs point at the same blob, so they share a cache entry.

Practical fallout:

1. For your own repos: push any commit that changes the affected file (even whitespace). That forces a fresh render and the <br>s come back. Hard refresh does nothing — the stale part is server-side.
2. For files you don't control, like the mermaid docs: nothing to do client-side; it heals whenever the file next changes upstream.
3. For your bug report, this gives you a much sharper ask than "GitHub doesn't recognise <br>": cached markdown renders aren't invalidated when the mermaid rendering pipeline changes its escaping/sanitization, so old-but-unchanged files break silently.

And if you want to check any given page in 10 seconds: inspect a diagram, find the js-render-enrichment-target div, look at data-json. Literal <br/> in there → stale render, tags will be stripped. <br/> → fine.

[andygout]

For your own repos: push any commit that changes the affected file (even whitespace). That forces a fresh render and the <br>s come back. Hard refresh does nothing — the stale part is server-side.

I have pushed a commit on a branch where I changed a file that contains Mermaid diagrams by adding "Foo" underneath the title.

On the basis of your suggestion, I would expect the rendering of the diagram for the commit on this branch to be a fresh render. However, the <br> tags are still present and the content is still being displayed inline.

[andygout]

I also pushed another commit that changed the text in the Mermaid diagram that includes the <br> tag and it still does not render correctly.

[antoniorotundo2]

That result is worth sitting with, because it falsifies the per-blob staleness theory as stated: if a fresh commit to the exact line containing <br> still renders broken, the cache being invalidated by commit history clearly is not the whole story, since that path was just tested directly.

The next cheap thing to check, before reaching for a new theory, is whether the server actually re-rendered anything at all. Same method Codebater used earlier: on the freshly committed page, find the js-render-enrichment-target div and read data-json directly. If it still contains the exact same escaping as before the commit, the render pipeline for this content never re-ran, which points at a cache keyed on something other than commit SHA or blob content, maybe the diagram source text itself, shared across files or even across repos with byte-identical Mermaid source. If data-json shows different content after the commit but the escaping is still the broken form, that is a different bug entirely, a code path that produces the wrong escaping on new renders too, not a caching problem at all.

One more targeted test that would distinguish those two: instead of editing text near the <br>, change the tag itself to something byte-different but semantically identical, <br/> instead of <br>, or add a harmless space inside it. If that alone fixes the render, the cache key is likely a hash of the diagram source text specifically, and the two of you were unlucky enough to keep re-submitting content that hashes to the same broken cache entry. If it does not fix it, that rules out content-hash caching and points back at the renderer's escaping logic itself.

If my answer was helpful to you, please consider marking it as the correct answer, thanks.