Mermaid diagrams in Confluence Cloud: how the options compare

If you have searched for this, you have probably found the first fact already: Confluence Cloud does not render Mermaid on its own. Paste a ```mermaid block into a page and you get a code block, not a diagram, and there is no setting to turn on. This page walks through four ways round that, including where each one is weaker, and where our own app fits and doesn't.

By Rolf Eriksen Published 10 November 2026 12 min read

Other products read on 10 November 2026, from the pages under Sources; our own app at version 2.9.0 · We make one of these apps (disclosure)

1. A static picture. Draw the diagram somewhere else, export a PNG or SVG, and attach it to the page. Free, and it looks the same in every export.
2. A free viewer macro. Keep the Mermaid text in an ordinary code block on the page, and add a macro that draws it. Atlassian Labs publishes one for free.
3. A general diagram tool that can read Mermaid. If your site already has draw.io, it can turn Mermaid text into a drawing.
4. A Mermaid macro app. Several Marketplace apps, ours included, add a Mermaid macro to Confluence.

How each option handles PDF and Word exports and dark mode depends on the product and its version, so run the four checks below on whichever you try.

Draw the diagram in Mermaid's own Live Editor, which needs no account, download a PNG or SVG, and attach it to the page. This works everywhere, in every export, theme and Confluence plan, because by the time it is on the page it is just a picture. That also means it stays exactly as drawn in dark mode.

The cost is that it is not live. Change one box, and you redraw and upload it again. Put the Mermaid text in an Expand element under the image, so the next editor finds it without hunting through your files.

Atlassian Labs publishes Mermaid diagrams viewer, a Marketplace app that was free on 10 November 2026. It draws a diagram from a Mermaid code block on the same page. You write or paste the Mermaid text as an ordinary code block and add the viewer's macro.

The appeal is that it costs nothing, and the text stays in a plain code block. Its listing makes the same point: even if the app breaks, the text is still on the page. The listing also says the code block can sit inside an Expand or at the end of the page, and that the viewer supports light and dark modes.

You write that code block by hand, so if a live preview, examples or help with syntax errors matter to you, check what the viewer's listing offers.

If your site already has draw.io for general diagramming, its editor can turn Mermaid text into a drawing. draw.io's Mermaid documentation puts it under Arrange → Insert → Mermaid.

On 10 November 2026, that documentation and draw.io's guide for Confluence Cloud describe two outputs, and you can edit the Mermaid text again with either. The default, "Diagram", turns it into draw.io shapes inside a Mermaid group. You can restyle those shapes, and editing the text redraws them and keeps your styling, though a shape you moved goes back to where the layout puts it. Ungrouping deletes the Mermaid text. "Image" makes a single SVG picture, which you change only by editing its Mermaid text.

Several Marketplace apps, ours included, add a Mermaid macro to Confluence. They all render Mermaid in a macro, so the differences show up at the edges: how many kinds of diagram an app covers, whether it helps you write the syntax, and, easy to miss until it happens to you, what the diagram looks like once it leaves the page.

Before you pick one, test these four things on a throwaway page, with whichever app you are trying:

• Export the page to PDF. Does the diagram print cleanly, without a toolbar in the picture?
• Export the page to Word. Does the diagram show up as a picture, or as Mermaid text in a code block?
• Switch your Confluence theme to dark. Does the diagram stay readable?
• Paste in a diagram from somewhere else: a GitHub README, an AI chat's answer, or another Mermaid app you are moving away from. Does the wrapping (the ``` fence, the chat's other text, the old app's saved format) come along, or does the app remove it?

The last one matters more than it sounds. Mermaid blocks turn up in AI chat answers and GitHub READMEs all the time, so it is worth knowing what happens when you paste one.

Two more things are worth knowing before a team depends on an app. Put a three-box diagram and a very wide one on the same page: can you read both without zooming? And ask what readers see if the licence lapses: the diagrams, or a notice in their place. A trial will not show you that one.

Mermaid Diagrams & Gantt for Confluence is in group 4: a macro with its own editor. It is one of several. Here is what version 2.9.0 does on the four checks and the two questions, so you can test it against whatever else you are considering.

• PDF and Word exports use a picture saved with the diagram. When you select Save, the editor stores a picture of the diagram, and exports use it, without the toolbar. So Word shows the diagram itself rather than its Mermaid text. Diagrams set to Auto export in light colours, unless their own text sets a theme; then they export on a background they can be read on.
• Colours start on Auto. Auto draws light colours on a light page and dark ones on a dark page. A diagram whose colours don't match the page, such as one whose own text sets a dark theme (answers from AI chats often do), sits on its own panel so its lines stay readable. The app decides that from the colours the diagram was actually drawn in, not only from the name of its theme.
• Pasting cleans itself up. Paste a fenced block from GitHub, a whole AI chat answer with one mermaid block in it, or the wrapping another Mermaid app for Confluence saves around a diagram, and the wrapping comes off. One Ctrl+Z (Cmd+Z on a Mac) gives you back exactly what you pasted.
• Diagrams show at a size people can read. A small diagram is not blown up to fill the page, and a wide one keeps its text readable and scrolls sideways, fading at the edge it continues past. Readers get a toolbar with zoom from 25% to 400%, Fit, which shows the whole diagram, and full screen; a double-click opens full screen too. Size on the page, in the editor, sets one diagram to fill the width or to its actual size instead. Before version 2.8, every diagram was stretched or shrunk to the page width.
• A lapsed licence stops editing, not reading. If the site's licence is not active, pages and exports keep showing each diagram as it was last saved, with its toolbar. Only the editor stops: it opens, says that editing needs an active licence, and does not save. Before version 2.8, pages showed a licence message in place of each diagram.
• Draft with AI and Fix with AI copy a ready-made prompt for the AI chat you already use: describe the diagram you want, or fix a syntax error. Paste the answer back, and the clean-up above removes the chat's text. The app itself never contacts an AI. What you paste into an AI chat goes to the company that runs it, so follow your organisation's rules.
• No permission scopes, nothing sent outside Atlassian. The app requests no scopes on install. Diagrams are stored in the page and drawn in your browser. For exports, page history and notification emails, Confluence hands each diagram to the app's own function on Atlassian's platform, which keeps nothing.

On 10 November 2026, the app is free for a site with up to 10 users. Above that it costs $0.35 per user per month for every user, and less per user above 100 users. The Marketplace listing has the current price.

Marketplace Documentation

A comparison page that hid its own weaknesses would not be an honest one, so here they are, as of version 2.9.0:

• You edit a diagram in the macro's editor, not on the published page. Confluence gives an app no way to open its own editor from the published view.
• Links on a box work in flowcharts only.
• It draws the 32 kinds of diagram in its examples, each with a built-in syntax reference. ZenUML, which Mermaid publishes as a separate package, is not one of them.
• A diagram taller than about 22 inches in Word, or too large to draw, gets no picture. The editor says so when you select Save and offers Save without picture; Word then shows that diagram's Mermaid text, and PDF draws it live.
• Diagrams saved before version 2.4, and diagrams saved before 2.6 that set their own theme or colours in a %%{init: ...}%% line or in front matter, need to be opened and saved once before Word shows them as a picture.
• A page with about 100 or more diagrams can hit a limit on Atlassian's export platform (CONFCLOUD-82734, still open on 10 November 2026), which can leave some diagrams out of the export.
• Notification emails show a diagram's text as code.
• While the site's licence is not active, diagrams can be read and exported but not changed: the editor does not save.
• It works on Confluence Cloud only, not Data Center.

More detail is under Current limitations in the documentation.

• One diagram, once, and it won't change? A static picture. Don't install anything for this.
• Comfortable writing Mermaid by hand, want it free, and don't need an editor? The free viewer macro.
• Already have draw.io and want one diagramming tool for everything? Try its Mermaid import, and choose between shapes you can restyle ("Diagram") and a single picture ("Image").
• Want an editor with a live preview, and diagrams that come out as pictures in Word and PDF exports? That is group 4. Run the four checks against whichever app you are considering, ours included, on your own content before you commit.

Step-by-step instructions for a static picture, the free viewer and a macro app are in How to add Mermaid diagrams to a Confluence Cloud page, and for draw.io in its Mermaid documentation.

• How to add Mermaid diagrams to a Confluence Cloud page: three of these options, step by step, and the problems people hit the first time.
• Gantt charts in Confluence Cloud, with Mermaid: for project plans, with the syntax and where it breaks down.
• Moving a diagram from another Mermaid app: copy and paste, and what the editor cleans up.
• Mermaid Diagrams & Gantt reference: every limit, export rule and stored value of our app.
• Trust center: what each of our apps can reach and stores.
• All guides.

What this page says about other products was read from the pages below on 10 November 2026. We did not install the viewer or draw.io to test them, so those sections say only what their own pages say. Vendors change their apps often; if a statement about your product is wrong, the address at the bottom reaches a person. What the page says about our own app describes version 2.9.0, released on 12 November 2026, and comes from its documentation and code.

• Mermaid diagrams viewer, by Atlassian Labs: its Marketplace listing (free; draws from a code block on the same page; the text stays on the page; Expand; light and dark modes) and its README (10 Nov 2026)
• Insert and edit a Mermaid diagram and Insert Mermaid as an SVG image, draw.io documentation: the menu, the two outputs, what editing keeps, ungrouping (10 Nov 2026)
• Create Mermaid diagrams in draw.io for Confluence Cloud, draw.io: editing the Mermaid text again with either output (10 Nov 2026)
• draw.io Diagrams, Marketplace listing: diagrams from Mermaid code are part of the app (10 Nov 2026)
• Insert the code block macro, Atlassian Support, and an Atlassian Community thread: a code block shows code, and pasted Mermaid blocks stay code (10 Nov 2026)
• Getting started, Mermaid, and the Live Editor itself: PNG and SVG downloads, used without signing in (10 Nov 2026)
• CONFCLOUD-82734, Atlassian: pages with a large number of Forge macros reach an invocation limit (10 Nov 2026)
• Mermaid Diagrams & Gantt for Confluence (ours): its listing and price on the Marketplace, and its reference (10 Nov 2026)

Changelog

• 12 November 2026. Updated for version 2.9.0 of our app. Under its limits, the built-in syntax reference now covers every kind of diagram the app draws, so that point now names the kind it does not draw. The other products were not read again and stand as of 10 November 2026.
• 10 November 2026. First version. Other products as of 10 November 2026; our app at 2.8.0.

Corrections

None yet. If a statement about your product is wrong or out of date, email [email protected] with the page that shows it, and we will change the text and record the correction here.