Mermaid Diagram in Confluence: 3 Ways to Add One
November 11, 2026 · 9 min read
Mermaid Diagram in Confluence: 3 Ways to Add One
To add a Mermaid diagram in Confluence, you need help from outside the page editor, because Confluence doesn't render Mermaid code by itself. Three routes work today: a Mermaid app from the Atlassian Marketplace, the Mermaid insert inside draw.io, or a PNG or SVG you export and upload. This guide compares them and gives you a tested example.
Can You Show a Mermaid Diagram in Confluence Without an App?
Not as a rendered picture. Neither Confluence Cloud nor Data Center documents a built-in Mermaid renderer. Atlassian's documentation for the code block macro lists its supported languages, from ActionScript to Visual Basic, and Mermaid isn't one of them. Paste Mermaid code into a code snippet and readers see the code, not a flowchart.
The same happens with Markdown. If you paste a file that contains a mermaid fence, the fence lands as plain text. Our guide to Markdown support in Confluence explains which typing shortcuts convert and which pastes don't. For diagrams, the answer is always an app or an image.
How Do I Add a Diagram to a Confluence Page? Three Routes Compared
Each route trades convenience against admin approval. Pick based on who controls your site's apps and how often the diagram changes.
| Route | Admin install needed | Edit inside the page | Mermaid code stays editable | Cost | Best for |
|---|---|---|---|---|---|
| Mermaid app macro | Yes | Yes, in the macro | Yes, inside the macro | Free and paid listings | Teams that draw diagrams weekly |
| draw.io Mermaid insert | Yes, draw.io is a Marketplace app | Yes, in the draw.io editor | Yes, reopen the Mermaid dialog | Paid app with a trial | Sites that already run draw.io |
| Exported PNG or SVG | No | No, you re-export each change | Only if you keep the source on the page | Free | Locked-down sites and one-off diagrams |
The first two routes keep the code and the picture together, which is what you want for living documentation. The third works anywhere you can attach a file, so it's the fallback when an app request sits unanswered for weeks.
Route 1: Install a Mermaid Diagram App for Confluence
A Mermaid diagram app for Confluence adds a macro that turns Mermaid text into a rendered diagram on the page. Installing one normally takes a site admin, so if you aren't one, plan on asking yours.
A Marketplace search for a Mermaid diagram for Confluence turns up several apps, and Mermaid's own integrations list links to more. Three listings show the range as of November 2026:
- Mermaid Chart for Confluence (Mermaid Chart Inc.) is listed as a free app for Confluence Cloud only, though creating and editing diagrams needs a Mermaid account.
- Mermaid Diagrams for Confluence (Stratus Add-ons) is paid with a free trial, for Cloud and Data Center.
- Mermaid Charts & Diagrams for Confluence (weweave) is paid with a free trial, for Cloud, Server and Data Center, and offers PNG, SVG and PDF downloads.
We don't endorse any of them. Check each listing's hosting, price and requested permissions before you ask your admin.
Once an app is installed, the flow is similar everywhere:
- Edit the page and type
/, then search for the app's macro, usually by typing mermaid. - Paste your Mermaid code into the macro editor.
- Check the preview, then insert or save the macro.
Route 2: Insert Mermaid Code Through draw.io
If your site already has draw.io, you can skip a dedicated Mermaid app. The draw.io instructions for Confluence Cloud go like this:
- Type
/drawon the page and select draw.io Diagram. - Name the diagram and click Create.
- Click the plus (+) icon and choose Mermaid, or go to Arrange, Insert, Mermaid.
- Paste your code and click Insert.
draw.io offers two insert modes. Diagram, the default, converts the code into editable shapes you can restyle one by one. Image keeps the result as a single SVG. Either way, you can reopen the Mermaid source later, change it and click Apply to regenerate the drawing.
Route 3: Export a PNG or SVG and Upload It to the Page
When nobody will install an app, render the diagram yourself and attach it. Paste your code into our Mermaid editor, which runs in your browser with a live preview, sample templates and theme selection. Then click Download SVG, or pick a PNG scale of 1x, 2x or 3x and click Download PNG. Before you download, our guide to Mermaid JS themes describes what each built-in theme looks like.
In Confluence Cloud, Atlassian's page on displaying files and images lists three ways to add the file. Drag it onto the page, use the Add image, video, or file button, or type /images and choose Image, video, or file. Select the image afterwards and choose Edit alt text to describe the diagram for screen readers.
We prefer SVG because it stays sharp at any zoom level. Atlassian's page doesn't say how SVG files display, though, so preview the page first. If the SVG looks wrong, a 2x PNG is the safe choice. Our Mermaid to PNG guide compares four export methods and explains how to keep the image sharp.
The limitation is real: an uploaded image is static. Every change means editing the code, exporting again and replacing the file. There's also no connection between our tool and Confluence, so you always download and upload by hand.
Keeping the Mermaid Source Under an Exported Image
An image without its source is a dead end for the next person who edits the page. Put the Mermaid code directly below the picture so anyone can paste it back into a renderer.
Two Confluence elements work well for this. An Expand element hides the code behind a title such as View diagram source. Atlassian's expand docs say you type /, pick Expand and add the content inside. On sites that still use the legacy code block macro, its Collapsible option folds the code on page load instead.
This habit also protects you from app trouble. If a Mermaid app is removed, or an update breaks its macro, you still own the text. The next change becomes a quick re-export instead of a redraw from a screenshot.
Testing a Release Approval Flowchart Before You Paste It
Test your code before it reaches Confluence, because a macro error on a shared page is more visible than one in a scratch tab. Here's a release approval flow written for a typical wiki page:
flowchart TD
A[Draft release notes] --> B{Product owner review}
B -->|Approved| C[Publish to the Releases space]
B -->|Changes needed| D[Update the draft]
D --> B
C --> E[Notify the support team]
It renders as a top-down chart. The curly braces draw the review step as a decision diamond, and -->|text| labels the two arrows that branch from it, per the Mermaid flowchart syntax. The Changes needed arrow loops back to review, so the chart shows the cycle rather than a straight line. For sequence diagrams, Gantt charts and the other types, see our Mermaid diagrams in Markdown guide. Edit the demo below and the preview redraws as you type:
Copy only the lines between the fences into an app macro or the draw.io dialog. Those dialogs expect raw Mermaid code, not a Markdown fence.
Will the Diagram Survive Confluence PDF Export?
An uploaded PNG is an ordinary image attachment, so it exports with the page like any other picture. Atlassian doesn't document how SVG attachments export, so check the PDF if you uploaded one. App macros are a different story, because the vendor controls how its macro renders in exports. The weweave listing, for example, advertises Confluence export integration. Test a PDF export with one page before you commit a whole space to an app.
Moving pages out of Confluence raises the same issue. The Confluence to Markdown converter turns pasted wiki markup or storage-format HTML into Markdown, but an app macro won't come through as a diagram. The source you kept under the image is what you paste back into a mermaid fence.
A Mermaid diagram in Confluence comes down to one choice: install an app, use draw.io, or upload an image. If your admin approves apps, a macro keeps code and picture together. If not, build the chart in our Mermaid editor, download an SVG or PNG, and attach it with the source kept in an Expand element beneath it.