Mermaid Live — User guide

What Mermaid Live does

Mermaid Live renders Mermaid diagrams on Confluence Cloud pages. You type or paste Mermaid source into a macro, watch the diagram take shape as you type, and get the same diagram as a full-size image when the page is exported to PDF or Word.

Everything runs on Atlassian's Forge platform. There is no account to create and no external service: the App makes no requests to any server outside Atlassian, and the diagram source and its rendered images are stored in your Confluence pages and in Forge app storage.

Diagrams are rendered with Mermaid 11. Flowcharts, sequence, class, state, ER, Gantt, pie, mind maps, git graphs, user journeys, timelines, and quadrant charts are all supported.

Adding a diagram

Edit a page, type /mermaid, and pick Mermaid Live. The macro opens straight into the editor — there is no template to choose and no separate app to visit.

Type or paste your Mermaid source, then save. The diagram appears on the page, and a rendering is stored at the same time so exports can embed it later.

The editor

The editor is a two-pane view: Mermaid source on the left, with syntax highlighting and line numbers, and a live preview on the right that follows your keystrokes. Drag the divider to give either side more room.

When the source has a syntax error, the editor shows the parser's message and keeps the last good preview dimmed behind it, so the picture never blinks away mid-edit.

Save a diagram type with no content yet — a lone “graph TD”, say — and the page shows a short “no elements yet” note instead of an empty box.

Each diagram can be shown as the picture, the source, or both. The choice is saved with the macro.

Each diagram also has a Theme setting — light or dark — saved with the macro, so diagrams can stay readable on a dark Confluence theme.

Zoom and full screen

Click a diagram to open it full screen. It fits the window when it opens; from there the mouse wheel zooms around the cursor, dragging pans, and the toolbar has Fit, + and − buttons. A 200-node flow chart is readable instead of a thumbnail.

PDF and Word export

Use Confluence's own export (Export → PDF / Word). With Pro, diagrams come out as full-size images — not code blocks, not blank boxes.

Nothing silently disappears or goes stale: a diagram that has never been rendered, or whose source changed after its last successful render, exports as its Mermaid source in a code block instead of a wrong or missing picture. On the Free plan, every diagram exports as its source code block.

Free and Pro

The editor, live preview, rendering, zoom, and full screen are free. PDF and Word export with the diagram embedded is part of the Pro plan; sites with up to 10 users use Pro for free, and a 30-day free trial is available.

Known limitations

Include Page shows no diagram

Confluence does not run Forge apps inside the Include Page macro, so an included page shows no diagram — nothing any app can change. Instead, wrap the diagram in an Excerpt on the source page and use Insert Excerpt: the diagram then displays and exports normally.

Pages created by scripts or the REST API

A page created by a script or the REST API and never opened in the Confluence editor may export incompletely — the PDF can stall or come out without the body. Open the page in the editor once and press Update; exports work from then on. Pages written in the editor are never affected.

Version view and version compare

When you open a page's version history or compare two versions, Confluence does not give apps the context they need, so a diagram may appear there as its Mermaid source or as an empty area. The current page, and PDF and Word exports, are unaffected.

Support

Write to us and we will answer within two business days. Tell us the page where it happens, what you typed, and what you expected to see.