# How to Share a Mermaid Diagram So It Actually Renders (2026)
Canonical: https://commareports.com/share-mermaid-diagram
Published: 2026-09-14
> Mermaid renders on GitHub and nowhere else your reader looks. Publish the diagram as HTML with mermaid.js inlined and send a URL that renders everywhere.
# Share a Mermaid diagram so it renders
You asked an agent for the auth flow and it gave you forty lines of
`sequenceDiagram`. On GitHub that is a picture. In the Slack thread where the
actual conversation is happening, it is forty lines of text starting with
`participant`.
Mermaid is a JavaScript library. Diagrams render where something runs that
library, and nowhere else.
## Where Mermaid renders, and where it doesn't
| Renders | Shows raw text |
| --- | --- |
| GitHub, GitLab | Slack, Teams, Discord |
| Notion, Obsidian | Gmail and every other mail client |
| VS Code preview | Jira, Linear, Confluence¹ |
| mermaid.live | Google Docs, Word |
¹ Confluence needs a paid marketplace app.
The pattern is consistent: developer tools render it, and the places where
decisions get signed off do not. Which is a problem, because architecture
diagrams exist to be reviewed by people who are not in your editor.
## Render it into a page
A Mermaid definition becomes a shareable page with about ten lines of
scaffolding:
```html
Auth flow
sequenceDiagram
Client->>Gateway: POST /session
Gateway->>Auth: verify(credentials)
Auth-->>Gateway: token
Gateway-->>Client: 201 + cookie
```
Publish that file and you have a URL. The reader opens it on a phone, in a
meeting, from a calendar invite — no extension, no account, no "can you export
it as a PNG?".
Comma renders report HTML inside a sandboxed iframe — `allow-scripts` without
`allow-same-origin` — so the Mermaid script runs while having no access to
anything else. That is the same mechanism behind
[interactive HTML reports](/interactive-html-reports).
## Why not a screenshot
Because a screenshot of a diagram is where review goes to die. It cannot be
searched, the text blurs at the zoom level a reviewer actually uses, and the
correction — "the gateway calls auth *before* the rate limiter" — arrives as a
Slack message with no anchor to the arrow in question.
A rendered page keeps the SVG text selectable and lets the objection land next
to the diagram, per [commenting on HTML](/comment-on-html). The broader case
against the screenshot habit is in
[stop screenshotting reports](/stop-screenshotting-reports).
## Diagrams an agent drew
Mermaid is the format coding agents reach for by default, which means most
architecture diagrams now start as agent output. An agent that can publish
returns the rendered URL instead of a fenced block you have to re-home:
> Render the sequence diagram as a Mermaid definition inside an HTML page,
> publish it, and reply with only the URL.
See [where should my agent post](/agents/where-should-my-agent-post).
## Worth knowing
- **Pin the mermaid version.** `@11` rather than `@latest` — a diagram that
renders today should render next quarter.
- **Large graphs need a scroll container.** `flowchart` output can exceed the
viewport; wrap the `` in a div with `overflow: auto`.
- **Put the definition in the page.** Keeping the source visible below the
rendered diagram makes the next revision a text edit rather than a redraw.
- **5 MB per report body** — far beyond any diagram.
## Try it
Free — unlimited reports, commenters and revisions.
**[Publish a diagram →](/docs/quickstart)**
### Related
- [Share a PlantUML diagram](/share-plantuml-diagram) ·
[Share a Graphviz diagram](/share-graphviz-diagram)
- [Share a draw.io diagram](/share-drawio-diagram) ·
[Share an Excalidraw drawing](/share-excalidraw-drawing)
- [Interactive HTML reports](/interactive-html-reports) ·
[Commenting on HTML](/comment-on-html)