Our complete guide to diagrams and flowcharts in Markdown covers Mermaid syntax in depth — flowcharts, sequence diagrams, ER diagrams, the works. What it doesn’t dwell on is a problem that shows up the moment you try to actually use one of those diagrams somewhere other than a GitHub README: most of the places you’d want to paste a diagram don’t render Mermaid at all.

That’s not a syntax problem, and no amount of getting the Mermaid code “right” fixes it. It’s a rendering-engine problem — Slack, Jira, Confluence, Word, and email clients simply have no Mermaid interpreter anywhere in their pipeline. The fix isn’t better Markdown. It’s exporting the diagram as a plain image before it leaves your Mermaid source.

Why this keeps catching people off guard

Mermaid fences (mermaid ) look exactly like any other fenced code block, and on the platforms that *do* support it — GitHub, GitLab, Obsidian — that fence quietly becomes a rendered diagram with zero extra steps. It's easy to assume the same thing will happen everywhere else, because nothing about the syntax signals "this only works in three places." It doesn't error. It doesn't warn you. It just shows up as a gray code block of flowchart TD` and arrow syntax, exactly as literally typed, and the reader has to reconstruct the diagram in their head from the text.

We ran into this from the other direction first, while documenting our own conversion tools: our Notion conversion guide, Word/DOCX guide, and Email HTML guide all independently document the same fallback: a Mermaid fence gets carried through as an inert code block, with a warning, because there’s no other honest thing a converter can do with syntax the destination format can’t execute. Slack and Jira have the identical gap for a different reason — there’s no conversion step at all, since you’re typically composing directly in Slack’s message box or Jira’s editor, and neither one has ever implemented a Mermaid renderer.

The fix: render it once, export a static image

The workaround is the same regardless of destination: render the Mermaid source into an actual image — SVG or PNG — outside the target platform, then paste or attach that instead of the Mermaid code. Once it’s a PNG or SVG, every platform on this list handles it exactly the same way it handles any other image, because at that point it is just an image.

You can do this with the Mermaid CLI (mmdc) if you’re comfortable with a Node toolchain and want it scripted into a build step — our diagrams guide covers that command-line path. For a one-off diagram, or if you don’t want to install anything, our Markdown Mermaid Diagram Preview tool does the same rendering step in the browser: paste your Mermaid source, see it render live (so you catch syntax errors before you export, not after you’ve already pasted a broken image somewhere), then use Download SVG or Download PNG to get a static file with nothing installed.

Platform by platform

Slack

Slack has no diagram rendering of any kind — not in the message composer, not via the API, not through Block Kit. A Mermaid fence pasted into a Slack message just shows up as plain text with backticks, per our Markdown to Slack guide, which documents the same “no native rendering, period” behavior for tables and several other Markdown constructs. Export a PNG and drag it into the message instead — Slack handles inline image previews natively, and unlike a wall of Mermaid syntax, a teammate can actually read it without decoding the diagram in their head.

Jira

Neither Jira’s classic wiki markup nor its modern Cloud rich-text editor has a Mermaid renderer, as our Markdown to Jira guide notes for wiki-markup conversion generally. Some teams install a marketplace add-on (several exist specifically for embedding live Mermaid/PlantUML diagrams in Jira issues), which is worth it if diagrams are a constant part of your workflow — but for an occasional diagram in a ticket, attaching an exported PNG is faster than getting a marketplace app approved and installed.

Confluence

Confluence’s /markdown paste panel strips or escapes raw HTML and doesn’t execute embedded scripts, so a Mermaid fence pasted in comes through as a plain code-formatted block, consistent with what our Confluence compatibility guide documents for other unsupported constructs. As with Jira, marketplace add-ons exist for live Mermaid rendering in Confluence pages if you need diagrams to stay editable in place; for a document going out once, attach the exported image and move on.

Word (.docx)

A .docx file has no code-execution layer at all — there’s no such thing as a “live” Mermaid diagram inside a Word document, full stop. Our Markdown to Word guide documents that our own markdown-to-docx converter drops Mermaid fences to a plain monospace code block with a warning, for exactly this reason — there’s nothing else a converter could do with it. Export the diagram as a PNG first, then either paste it directly into the document or use our Markdown Image Formatter if you want a sized/captioned version before it goes in.

Email (newsletters, transactional templates)

Same root problem as Word, for the same reason: email clients render HTML, not JavaScript, and Mermaid needs JavaScript to do its layout work. Our Markdown to Email HTML guide documents the identical fallback — a Mermaid fence becomes a plain code block with a warning banner. For email specifically, export PNG, not SVG: SVG support in email clients is inconsistent (particularly in Outlook’s desktop Word-based rendering engine, already a recurring theme in that guide), while a PNG is universally safe.

SVG vs. PNG: which to export

Reach for SVG when the destination platform accepts vector images and you might need to resize or embed the diagram at multiple sizes — a wiki page, a MkDocs/Docusaurus site that doesn’t render Mermaid live, a print-quality document. SVG stays crisp at any zoom level and is a much smaller file for simple diagrams.

Reach for PNG for everything else in the list above — Slack, Jira, Confluence attachments, Word, and especially email — where universal support matters more than infinite scalability, and where you can’t be sure the destination will render an <img> pointing at an SVG correctly. Our tool exports PNG at 2x scale specifically so it still looks sharp on a high-DPI display without needing SVG’s true vector scaling.

Quick reference

Destination Native Mermaid rendering? What to do instead
GitHub, GitLab, Obsidian Yes, built in Nothing — paste the fence directly
Slack No, none Export PNG, attach/drag into message
Jira No (marketplace add-ons exist) Export PNG, attach to issue
Confluence No (marketplace add-ons exist) Export PNG, attach to page
Word (.docx) No, no execution layer at all Export PNG, insert as image
Email (ESP / HTML template) No, no execution layer at all Export PNG (not SVG), inline in template
MkDocs / Docusaurus Needs a plugin, off by default Export SVG for a self-hosted static asset, or enable the plugin