Mermaid in Confluence
Mermaid turns a few lines of text into a diagram; in Confluence an app draws that text on the page, so a diagram is fixed by editing a line.
Last updated
What Mermaid is
Mermaid is an open-source language for diagrams. You describe the diagram in text and Mermaid draws it:
flowchart LR
Draft[Write the page] --> Review{Reviewed?}
Review -- Yes --> Publish[Publish]
Review -- No --> Draft
These four lines are a flowchart with three steps and a loop. To add a step you add a line. Nobody opens a drawing tool, and nobody looks for the original file.
Why write diagrams as code
- The diagram stays right. A picture goes out of date because fixing it needs the source file and the tool. Code is fixed where it is read, by anyone who can edit the page.
- Changes are visible. The code is text, so the page history shows what changed in a diagram and who changed it.
- Search finds it. With Vellnar Diagrams the words in the code are indexed with the page, so a Confluence search for a service or a table name finds the page with the diagram.
- The layout is automatic. You say what connects to what; Mermaid places the boxes and the arrows.
How it works in a Confluence page
Confluence Cloud has no built-in Mermaid macro: Atlassian’s documentation of the code block, of the built-in macros and of the elements you can insert does not list one (checked on 21 November 2026). A Marketplace app adds the macro. With Vellnar Diagrams:
- Edit a page and type
/mermaidwhere the diagram should go. - Select Mermaid diagram. The editor opens with 72 templates.
- Pick a template or type your own code. The preview follows every keystroke and marks the line with an error.
- Choose Save. The diagram is on the page, and readers can open it in full screen, zoom, search its labels and export it.
The code is saved inside the page. The page’s permissions decide who sees the diagram, and copying, moving or restoring the page does the same to the diagram. The documentation describes every step with screenshots.
What to check when you choose an app
Several Marketplace apps draw Mermaid in Confluence. They differ on facts that you can verify before you install:
- Where the code is stored: in the page, in an attachment, or in an account outside Atlassian.
- Permissions: what the app can read and write on your site. Confluence shows the list at install.
- Data outside Atlassian: whether the app has the “Runs on Atlassian” badge, and what it sends to its vendor.
- PDF export: whether a page exported to PDF contains the diagram, and how sharp it is.
- Viewing: full screen, zoom and search for diagrams larger than the page.
- Mermaid version: newer diagram types need a recent version.
- Price at your number of users, and what happens to the diagrams if the license ends.
Vellnar Diagrams stores the code in the page, asks for no permissions, makes no outside connection, puts a vector picture in PDF exports and draws with Mermaid 12.3. If its license ends, diagrams stay visible and only editing pauses.
We compared it with six other apps, with dated facts and the cases where the other app is the better choice:
- Mermaid Diagrams for Confluence (Stratus Add-ons)
- Mermaid Charts & Diagrams for Confluence (weweave)
- Macro Pack (Warsaw Dynamics)
- Mermaid Chart for Confluence (Mermaid Chart)
- Mermaid diagrams viewer (Atlassian Labs)
- Mermaid (Narva Software)
Every diagram type
Each page has what the diagram is for, example code and the templates that come with the app.
- Core engineering: Flowcharts, Sequence diagrams, Class diagrams, State diagrams, ER diagrams, Git graphs
- Cloud & system design: Architecture diagrams, C4 diagrams, Block diagrams, Packet diagrams, Tree views
- Flows & modelling: Swimlane diagrams, Event models, Use case diagrams, Requirement diagrams
- Delivery, metrics & data: Gantt charts, Sankey diagrams, XY charts, Treemaps, Timelines, Pie charts, Kanban boards
- Analysis, UX & strategy: Ishikawa diagrams, Mind maps, Quadrant charts, User journeys, Radar charts, Wardley maps, Cynefin diagrams, Venn diagrams
Common questions
Does the diagram appear when the page is exported to PDF?
Yes. Vellnar Diagrams puts a vector picture of the diagram in the PDF, on one page or at actual size, as you choose in the diagram settings. A Word export contains the diagram code.
Can people who do not know Mermaid use it?
They can read, open, zoom and export every diagram with no knowledge of the code. To write one, most people start from a template and change the labels; the preview shows each change at once.
What does the app need from our Confluence site?
Nothing. Vellnar Diagrams asks for no permissions and runs on Atlassian. The security page has the details.
Can we try it first?
Atlassian sells the app with a 30-day free trial. You can also try the editor on this site, with nothing to install.