Why does my Mermaid diagram show as code instead of a picture?

Because the surface you pasted it into does not run Mermaid. GitHub, GitLab and Notion render ```mermaid fences; Slack, email, Jira, Google Docs and most chat clients show the raw text. Mermaid is a JavaScript library, so something has to execute it.

How do I share a Mermaid diagram with someone who won't see the source?

Render it to a page. Wrap the definition in a small HTML file that loads mermaid.js and initializes it, publish that as a report, and send the URL — the reader gets the picture with no tooling and no account.

Should I export to PNG or SVG instead?

PNG loses the text layer and scales badly; SVG is better but can't be commented on in most places and still needs hosting. A rendered page keeps the diagram crisp, selectable, and linkable.

Can people comment on a specific part of the diagram?

They can comment on the diagram and on the prose around it, which in practice is what architecture review needs — the objection is usually 'this arrow is backwards', anchored next to the diagram.

My agent generated the Mermaid. Can it publish it too?

Yes. Rendering a Mermaid definition into a page template and publishing it is one API call, so an agent that produced the diagram can hand back a URL rather than a fenced code block.

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:

<!doctype html>
<meta charset="utf-8" />
<title>Auth flow</title>
<pre class="mermaid">
sequenceDiagram
  Client->>Gateway: POST /session
  Gateway->>Auth: verify(credentials)
  Auth-->>Gateway: token
  Gateway-->>Client: 201 + cookie
</pre>
<script type="module">
  import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
  mermaid.initialize({ startOnLoad: true });
</script>

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.

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. The broader case against the screenshot habit is in 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.

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 <pre> 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 →