Guide · Mermaid in Confluence
How to Add Mermaid Diagrams to Confluence
Confluence — Cloud and Data Center — has no built-in Mermaid macro, so diagram code pasted into a page renders as text. Marketplace apps add one, but every app needs a site admin to install it and most are priced per user. The zero-install route is to render the code in your browser and paste the exported image straight into the page, which works in every Confluence instance and costs nothing.
No signup · No app install · No watermark · Local browser rendering
Does Confluence support Mermaid natively?
Neither Confluence Cloud nor Data Center ships a Mermaid macro. The Atlassian Marketplace has several Mermaid apps, and draw.io's Confluence app can also insert Mermaid code — all of them need an admin install, and most are billed per user; Atlassian Labs publishes a free one. Pasting an exported PNG or SVG needs none of that: any page author can do it, in any space, today.
Add a Mermaid diagram to a Confluence page
- 1
Paste your Mermaid code
Drop your diagram code into the converter below. It renders locally in your browser — nothing is uploaded, which matters for internal architecture docs behind your firewall.
- 2
Match your space's look
Confluence pages are white, so the white background with the Clean Docs style reads like a native figure. If your space uses a dark theme, switch to GitHub Dark so labels stay readable.
- 3
Export PNG at 2x — or SVG
A 2x PNG stays sharp when readers zoom the page or print it. Confluence Cloud also displays SVG attachments, which scale cleanly for large architecture diagrams.
- 4
Drop it into the page
Drag the exported file into the Confluence editor — it attaches automatically and displays inline. Or use Insert → Files and images, then resize in place and add alt text so screen readers can describe the diagram.
Three ways to get Mermaid into Confluence
| Option | What you need | What readers see | Trade-off |
|---|---|---|---|
| Marketplace Mermaid app | A site admin to install it; most are paid per user | A live diagram, redrawn from the code on the page | Check which Mermaid version the app bundles — newer diagram types need a recent one |
| Atlassian Labs Mermaid diagrams viewer | A site admin to install it; free and open source; Cloud only | A diagram drawn from a code block on the same page | You write the code in a plain code block, so there is no side-by-side preview while editing |
| Exported PNG or SVG | Nothing — any page author can do it, in Cloud or Data Center | A fixed image in the style you chose | Editing means re-exporting, so keep the code in a code block under the image |
If a space admin will install an app and the diagrams change often, an app saves the export step. For a one-off figure, a page in a space you do not administer, or Data Center without the app, export it: the steps above take a minute, and the syntax checker catches errors before the image goes on the page.
Keep the diagram editable on the page
An image cannot be edited in Confluence, so put the Mermaid source in a code block directly under it — collapsed in an Expand macro if it is long. The next person copies the code, pastes it into the editor below, changes it, and replaces the attachment. Teams moving between tools can compare the options in draw.io vs Mermaid; for a document outside Confluence, the Word and Google Docs guides use the same export.
Export your diagram here
Paste your Mermaid code below, pick a style, and download the image. Everything renders locally in your browser — no signup, no watermark.
Export controls activate after your diagram renders locally.
Which export works best in Confluence?
Displays in every Confluence version and stays sharp when readers zoom or the page is exported to PDF. The safe choice for space-wide style guides.
Confluence Cloud displays SVG attachments at any zoom level without blur, which suits wide architecture and flow diagrams that readers will pan and expand.
JPG compression softens thin connector lines and small labels. PNG gives the same size with none of the artifacts.
FAQ
Questions about this workflow
Does Confluence support Mermaid diagrams?+
Not natively. Confluence Cloud and Data Center have no built-in Mermaid macro — you either install a Marketplace app or insert an exported image. The image route needs no app and no admin.
How do I add a Mermaid diagram to Confluence?+
Paste your code into the converter on this page, export a 2x PNG or SVG, then drag the file into the Confluence editor. It attaches to the page and displays inline — the whole workflow takes under a minute.
Is there a free Confluence Mermaid app?+
Marketplace Mermaid apps are typically billed per user, and some offer limited free tiers. If you just need diagrams in pages rather than live-editable macros inside Confluence, exporting an image costs nothing, installs nothing, and works in every space.
Is there a Mermaid macro for Confluence?+
No native one. Macros come from Marketplace apps, which render Mermaid code inside the page and usually need a paid license for your whole site. The app-free alternative is a PNG or SVG image, which any page author can paste.
Does the export-and-insert workflow work in Confluence Cloud and Data Center?+
Yes. Both lack a native Mermaid macro, and both display pasted PNG and SVG images, so the export-and-insert workflow works identically in each.
How do I update a diagram after the page is published?+
Keep the Mermaid code — or this editor's Share link, which carries the whole diagram. Edit the code, re-export the image, then upload it in Confluence as a new version of the same attachment: every page referencing that attachment picks up the new image.
PNG or SVG for Confluence pages?+
PNG at 2x is the dependable default. SVG is worth it for large architecture diagrams — Confluence Cloud renders it at any zoom without blur.
Is my diagram code uploaded anywhere?+
No. Rendering happens locally in your browser, so internal diagrams behind your firewall never leave your machine.
Is there a free Mermaid app for Confluence?+
Yes. Atlassian Labs publishes Mermaid diagrams viewer, a free, open-source app for Confluence Cloud: write the code in a code block and add the viewer macro to the page. A site admin still has to install it.
Does Confluence Data Center support Mermaid?+
Not out of the box. Data Center needs a Marketplace app that supports it, or an exported PNG or SVG pasted into the page, which works in every version.