Mermaid diagrams in Confluence Cloud: what actually works in 2026

Thijs from Dortus — Sun, 01 Nov 2026 12:03:07 +0000

If your team writes docs in Markdown, you probably have Mermaid diagrams lying around: in a README, in a pull request, or in an answer ChatGPT gave you. Then someone asks for the same diagram on a Confluence page, and it falls apart.

This is a short, practical rundown of what Confluence Cloud does with Mermaid, and the three ways to get a real diagram on the page.

Disclosure up front: I build one of the Confluence apps mentioned below (option 3). The other two options are free and work fine for many teams, so pick what fits.

What Confluence Cloud does on its own

Paste Markdown into the Confluence editor and it converts headings, lists, tables and code blocks. A fenced block like this:

```mermaid
flowchart TD
    A[Request] --> B{Approved?}
    B -- Yes --> C[Ship it]
    B -- No --> D[Send back]
```

becomes an ordinary code block. Readers see the code, not the diagram. Confluence Cloud has no Mermaid rendering built in (tested October 2026).

Option 1: export an image from mermaid.live

mermaid.live is the free online editor from the Mermaid project. Paste the code, download PNG or SVG, upload the image to the page.

Good: nothing to install.
Bad: the picture goes stale. When the process changes, someone has to find the original code, redraw and re-upload. If the code wasn't saved, they start from scratch.

Tip if you go this way: put the Mermaid code in a collapsed Expand under the image, so the next person can redraw it.

Option 2: a viewer that renders a code block

Atlassian Labs publishes a free, open-source app, Mermaid diagrams viewer. You keep the code in a normal Confluence code block and add the viewer macro to the same page; it draws the diagram from that block.

Good: free, made by Atlassian Labs, code and diagram live on the page.
Bad: you type the code in a plain code block, without a side-by-side preview, so mistakes show up later.

Option 3: an editor macro with a live preview

Several Marketplace apps add a Mermaid macro with an editor. The one I build is Mermaid Editor for Confluence: code on the left, the diagram on the right, redrawn as you type. If a line is wrong, the error names the line. On the page the diagram fits the width, opens large with zoom, and downloads as SVG or PNG. It runs on Atlassian Forge and draws in the reader's browser, with no external service.

When comparing apps in this category, three questions matter more than the feature lists:

Do you see a preview while you edit? Without one, every typo means publish, look, edit again.
Which Mermaid version does it bundle? Newer diagram types (architecture, kanban, timeline) need a recent Mermaid.
Where is the diagram drawn? In the reader's browser, or on the vendor's server? For internal architecture diagrams, that is a real question.

Getting a diagram from ChatGPT or Claude that renders first time

AI assistants write decent Mermaid, but a few habits save a lot of back and forth:

Describe the process, name the diagram type, ask for code only. For example:

  Draw the approval process for a purchase request as a Mermaid flowchart.
  An employee submits the request. The manager approves or rejects it.
  Above 5,000 euros, finance must also approve. After approval,
  purchasing places the order. Reply with only the Mermaid code.

Quote labels with brackets in them. A[Check stock (optional)] is a syntax error; A["Check stock (optional)"] works.
Paste the error back. If the renderer reports an error on a line, give the assistant that line and the message, and ask for a fix.
Strip the fences if your tool needs it. Some tools want the code without the ```mermaid lines; good editors remove them for you.

Which one to pick

One diagram that will never change: an image from mermaid.live, with the code saved under it.
A code block that readers should also see as a diagram: Atlassian Labs' viewer.
Diagrams people keep editing on the page, with a preview while they type: an editor macro.

If you've found another approach that works well in Confluence Cloud, I'd like to hear it in the comments.