Does Confluence Support Mermaid? 3 Ways to Add Diagrams

Short answer: Confluence Cloud doesn't render Mermaid on its own. Paste a Mermaid diagram into a page and you get a code block with the source in it, not a diagram. To draw it, add an app: a Mermaid macro such as Mermaid Diagram for Confluence, a Markdown macro that understands Mermaid, or an importer that turns the mermaid blocks in your .md files into diagrams as it creates the pages.

Mermaid is the diagram language developers already use. GitHub and GitLab draw it in READMEs, most docs-site generators support it, and a flowchart written as ten lines of text is easier to review and change than an image exported from a drawing tool. So when docs move into Confluence, the first question is usually what happens to the diagrams.

This guide covers the three routes and which one fits which job.

What Confluence does with Mermaid out of the box

Confluence's code block can be set to many languages, but Mermaid source in a code block stays as source. The editor has no Mermaid macro of its own, and the Markdown shortcuts it understands while you type don't include diagrams.

That leaves teams with three habits, none of them good:

Screenshots. Someone renders the diagram elsewhere and uploads a PNG. It looks right until the process changes, and then nobody has the source.
Code only. The Mermaid stays as a code block and readers are expected to picture it.
Link out. The page links to a diagram in a repository or the Mermaid Live Editor, which readers may not be able to open.

Each route below keeps the diagram as text inside Confluence and draws it on the page.

Option 1: A Mermaid macro

Best for: diagrams you draw and maintain in Confluence itself.

Mermaid Diagram for Confluence is a free app that adds a Mermaid Diagram macro. You write Mermaid on the left and the diagram updates on the right as you type.

Edit a page, type /mermaid and choose Mermaid Diagram.
Write a diagram, or click Templates and start from one of the 12 templates (flowchart, sequence, class, state, ER, Gantt, pie, mind map, timeline, user journey, Git graph and quadrant).
Click Save diagram and publish the page.

flowchart LR
    A[Pull request] --> B{Checks pass?}
    B -- Yes --> C[Merge]
    B -- No --> D[Fix and push]
    D --> B

Because the app is built only for diagrams, it goes further than drawing them:

Page trees. Insert a diagram of a page and the pages under it, as a flowchart or a mind map, where every box opens its page. See Page tree.
Links to pages. Right-click a flowchart box and link it to a Confluence page.
Colour themes. Admins create named themes with your brand colours, each with a dark-mode version, and every editor can pick them. See Colour themes.
Readers' tools. Zoom, full screen, the code view and a high-resolution PNG download sit under each published diagram.
Exports. PDF export uses a light-colour image of the diagram, and Word export includes the Mermaid code.

The app runs on Atlassian Forge and keeps diagrams in the app's Forge storage for your site, so nothing is sent to an outside server. If your team also uses Jira, Mermaid Diagrams for Jira draws the mermaid code blocks in issue descriptions and comments.

Option 2: Mermaid inside a Markdown macro

Best for: pages you already write in Markdown, where the diagram sits between headings, tables and code.

Markdown Macro+ for Confluence renders Mermaid inside its Markdown editor. You write a fenced code block with mermaid as the language, and the macro draws it in the preview and on the published page.

Type /markdown on a page and insert Markdown Macro+.
Start a fenced code block marked mermaid, write the diagram and close the block.
Check the preview, save the macro and publish.

## Deploy flow

Every merge to main runs the same pipeline:

```mermaid
sequenceDiagram
    participant Dev
    participant CI
    participant Prod
    Dev->>CI: Merge to main
    CI->>CI: Build and test
    CI->>Prod: Deploy
```

If the deploy fails, CI rolls back to the last good release.

The diagram is one block in the page, so a runbook can open with a flowchart of the process and follow it with the commands for each step. The same mermaid block you have in a README works here unchanged. More examples are in the Mermaid diagrams guide, and Confluence wiki markup vs Markdown explains where Markdown fits in Confluence in general.

Option 3: Import Markdown files with Mermaid in them

Best for: an existing docs folder or repository, with diagrams already written.

If your diagrams live in .md files, adding them one by one is the slow way. Markdown Importer for Confluence imports a single file, many files or a ZIP of folders as a page tree, and it can turn every mermaid code block it finds into a diagram on the new page.

A Confluence admin sets it once for the site:

Go to Confluence Settings and, under Apps, select Markdown Importer for Confluence.
Open the Import settings tab.
Under Mermaid diagrams, choose an option. It saves straight away.

Option	What each `mermaid` block becomes
Keep as code blocks (default)	A code block with the diagram source
Render with Mermaid Diagrams	A Mermaid Diagram macro, drawn on the page and editable in its live editor (needs Mermaid Diagram for Confluence)
Render with Markdown Macro+	A Markdown Macro+ macro that draws the diagram (needs Markdown Macro+)

Then import as usual: open a page's ••• menu, choose Markdown Importer & Exporter, pick your files or a ZIP, preview and click Import. The setting also applies to imports through the importer's REST API, so a CI job that publishes docs on every merge gets diagrams too. How to sync GitHub docs to Confluence automatically walks through that setup.

A few things to know before a big import:

Install the app you choose first. If it isn't installed, pages show Confluence's placeholder for a missing app instead of the diagram.
Top-level diagrams only. Confluence doesn't allow macros in every place, so diagrams inside lists, quotes or tables stay as code blocks.
New imports only. Changing the setting doesn't touch pages you imported earlier.
Government Cloud sites only offer Keep as code blocks for now.

The full reference is in the importer's Mermaid diagrams docs. For the import itself, see How to import Markdown into Confluence or, for a whole repository, Migrate GitHub and GitLab docs to Confluence.

Which one should you use?

You want to	Use
Draw and maintain diagrams in Confluence, with templates, page trees and brand colours	Mermaid Diagram for Confluence
Keep diagrams inside Markdown pages, next to text, tables and code	Markdown Macro+
Bring a docs folder or repository across with its diagrams drawn	Markdown Importer, set to one of the two above

The routes work together. A common setup is Markdown Importer set to Render with Mermaid Diagrams for the migration, then the Mermaid macro for new diagrams, so every diagram on the site has the same editor and the same colour themes. Teams that keep their docs in Markdown on both sides pick Markdown Macro+ instead, and can export pages back to .md later; see Confluence to Markdown: 4 ways to export.

Frequently asked questions

Does Confluence Cloud support Mermaid natively?

No. Confluence Cloud has no built-in Mermaid macro, and a Mermaid diagram pasted into a page stays as code. An app from the Atlassian Marketplace is needed to draw it.

Is there a free Mermaid app for Confluence?

Yes. Mermaid Diagram for Confluence is free on the Atlassian Marketplace and runs on Atlassian Forge.

Which Mermaid diagram types work in Confluence?

With Mermaid Diagram for Confluence, every type Mermaid supports, including flowcharts, sequence, class, state, entity relationship, Gantt, pie, mind map, timeline, user journey, Git graph and quadrant charts.

Can I import a README with Mermaid diagrams into Confluence?

Yes. Markdown Importer for Confluence imports the README as a page. Set its Mermaid option to Render with Mermaid Diagrams or Render with Markdown Macro+ first, and each top-level mermaid block becomes a diagram instead of code.

Do Mermaid diagrams show up in Confluence PDF exports?

With Mermaid Diagram for Confluence, yes: PDF export uses a light-colour image of the diagram, and Word export includes the Mermaid code.

Can I edit an imported diagram later?

Yes. A diagram imported with the Mermaid Diagrams option is a normal Mermaid Diagram macro, so anyone who can edit the page can open it in the live editor and change it.

Try it

Install Mermaid Diagram for Confluence from the Atlassian Marketplace, type /mermaid on a page and start from a template. If your diagrams are already in Markdown files, add Markdown Importer for Confluence and set its Mermaid option before you import. The Mermaid Diagram docs and the quick start cover the rest.