Aldorock apps for Atlassian

Diagram Macros for Confluence · Guide

How to add Mermaid diagrams in Confluence Cloud

Confluence Cloud does not draw Mermaid diagrams by itself. Paste Mermaid text into a code block and readers see the text, not the picture. To draw it you need a macro from the Atlassian Marketplace, such as the Mermaid diagram macro in Diagram Macros for Confluence.

What Confluence does without an app

The Confluence editor has code blocks with syntax highlighting, and whiteboards for drawing by hand. Neither turns Mermaid text into a diagram. You can draw the diagram in another tool and upload a picture, but then the picture and its source live in two places and drift apart after the first change.

Step by step with Diagram Macros

  1. Install Diagram Macros for Confluence from the Marketplace listing. A Confluence admin does this once for the whole site.
  2. Insert the macro. Edit a page and type /Mermaid, or pick Mermaid diagram from the + menu.
  3. Write the diagram. The macro editor opens with an example and a live preview. The Start from list loads a working flowchart, sequence diagram, Gantt chart, class diagram, state diagram or pie chart. Paste your own Mermaid text on the left and the preview redraws as you type.
  4. Fix mistakes. If a line is wrong, the preview shows the line number and what Mermaid expected. Save stays disabled until the diagram parses, so a broken diagram never reaches the page.
  5. Set the look. Pick a theme (default, neutral, dark or forest), a width from 10 to 100 percent of the page, the alignment and an optional caption.
  6. Save and publish. Press Save, then publish the page. To change the diagram later, select the macro in the editor and click the pencil.

The Mermaid diagram macro editor with the Mermaid text on the left and a live preview on the right

Which Mermaid diagrams work

The app bundles Mermaid 11 and accepts the diagrams it understands: flowchart, sequenceDiagram, gantt, classDiagram, stateDiagram-v2, erDiagram, pie, journey, mindmap, timeline, gitGraph, quadrantChart, xychart-beta, block-beta, sankey-beta and C4 diagrams.

A published Confluence page with a flowchart and a sequence diagram drawn by the Mermaid macro

Good to know

Price

Free for up to 10 users. From 11 users it costs 0.30 USD per user per month, billed by Atlassian. The Pricing tab on the listing shows the exact figure for your user tier, and you can try the app free for 30 days before you pay.

Get Diagram Macros for Confluence on the Atlassian Marketplace

More guides