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.

RouteAdmin install neededEdit inside the pageMermaid code stays editableCostBest for
Mermaid app macroYesYes, in the macroYes, inside the macroFree and paid listingsTeams that draw diagrams weekly
draw.io Mermaid insertYes, draw.io is a Marketplace appYes, in the draw.io editorYes, reopen the Mermaid dialogPaid app with a trialSites that already run draw.io
Exported PNG or SVGNoNo, you re-export each changeOnly if you keep the source on the pageFreeLocked-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:

  1. Edit the page and type /, then search for the app's macro, usually by typing mermaid.
  2. Paste your Mermaid code into the macro editor.
  3. 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:

  1. Type /draw on the page and select draw.io Diagram.
  2. Name the diagram and click Create.
  3. Click the plus (+) icon and choose Mermaid, or go to Arrange, Insert, Mermaid.
  4. 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:

Release approval flow

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]

Change a label, then copy the lines between the fences into your Confluence macro.

51 words320 characters12 lines
Markdown

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.