Mermaid Macros for Confluence
Setup & Usage Guide
Installation
Install Mermaid Macros for Confluence from the Atlassian Marketplace. The app adds a Mermaid Diagram macro to the Confluence page editor.
No configuration is required. The macro is available immediately after installation.
Working in Jira instead? See Mermaid Diagrams for Jira, the companion app that auto-renders mermaid code blocks in Jira issues.
How It Works
Unlike the Jira app, which auto-detects code blocks, the Confluence app works through a macro. This is because Confluence's editor model is different from Jira's: you insert the macro exactly where you want the diagram, and it renders inline as an interactive SVG at that location.
- In the page editor, type
/Mermaidand select Mermaid Diagram - Write or paste your Mermaid source in the editor. It has syntax highlighting and a live preview that renders as you type. New to Mermaid? Pick a starter from the Insert example menu.
- Click Save (or press
Cmd/Ctrl+Enter); the diagram renders inline at that location
For example, paste the following Mermaid source into the macro:
flowchart LR
A[Start] --> B[Process]
B --> C{Decision}
C -->|Yes| D[Done]
C -->|No| B
Supported Diagram Types
Features
Editor with Live Preview
Syntax-highlighted editor with line numbers and a side-by-side preview that renders as you type. Syntax errors show the reason and highlight the offending line. Starter templates cover 8 diagram types.
Diagrams in PDF Exports
Export a page to PDF and your diagrams appear fully rendered: clean output with no UI controls. Word exports include the diagram source as a readable code block.
Display Options
Choose per macro what the page shows: the diagram, the source code, or both together.
Import from Mermaid Live Editor
Paste a mermaid.live share link into the editor and the diagram imports instantly, decoded from the link itself, with nothing fetched from external servers.
Inline Rendering
Diagrams render directly on the page where you place the macro, so they read as a natural part of your documentation, including inside Expand sections.
Zoom Controls
Fit the diagram to the panel or zoom in and out to inspect fine detail in complex diagrams.
Export & Copy
Copy or download any diagram as SVG or PNG, straight from the macro.
Dark & Light Mode
Theme-aware rendering automatically syncs with your Confluence theme, re-rendering diagrams with the correct color palette when you switch modes.
Per-Diagram Error Handling
If a diagram has a syntax error, the macro surfaces a clear, per-diagram message instead of breaking the page.
Pro: Optional Styling Upgrade
Version 4 adds Pro, an optional upgrade that is entirely about styling: no core feature has been moved behind it. Clean and Hand-drawn styles stay free.
- Nine designed styles: Boardroom, Sketchbook, Blackboard, Cupertino, Workshop, Phosphor, Blueprint, Newsprint, and Aurora. Each comes with a matching bundled font and covers every diagram type.
- Saved with the macro: pick a style once in the macro editor and every viewer of the published page sees the same styled diagram.
- Right-angle connectors: one toggle for orthogonal (ELK) edge routing that keeps large flowcharts, state and class diagrams readable.
Version 3 remains free forever; sites that stay on v3 keep everything they have. Updating to v4 starts a subscription: $0 for teams of 10 or under. Current pricing is on the app's Atlassian Marketplace pricing tab.
Works with Rovo
Ask Rovo for a diagram in plain English ("make me a flowchart of our release process, in Mermaid syntax"), then paste the result into the macro editor and watch it render in the live preview. Refine it in plain English, paste the update, save.
Rovo writes valid Mermaid out of the box; the macro is what turns it from text into a live diagram. No AI account to create and no extra fee from us: Rovo is included in Atlassian Standard and higher plans.
Privacy & Security
The app is built for privacy by default. It runs entirely on Atlassian Forge and renders everything in your browser.
- Zero data-access permissions: the app requests no scopes at all (an empty scope set), so it cannot read, create, or modify any of your content.
- In-browser rendering: rendering happens in the browser and page exports are generated inside Atlassian, so your diagram source stays in Confluence unless you deliberately take it somewhere.
- Atlassian-only: the app never communicates with any service outside Atlassian: no analytics, no tracking.
- Compliance: inherits SOC 2 Type II and GDPR compliance from the Atlassian Forge platform.
Learning Mermaid syntax
Mermaid is an open text-to-diagram syntax: the same code works here, in any other Mermaid tool, and in plain text files. Three places worth knowing:
- Our Mermaid cheat sheet: copy-pasteable starters for the diagram types teams actually use in Jira and Confluence, plus the six tips that save the most time.
- mermaid.js.org: the official documentation, and the complete reference for every diagram type and option.
- Mermaid Live Editor: a scratchpad for drafting and checking syntax before you paste it in.
Creating diagrams via the REST API
The macro's configuration is stored as plain values in the page body, so scripts, templates, and AI assistants can create and edit diagrams through Confluence's standard page API; no app-specific API needed. The macro is an ADF extension node; its settings live in parameters.guestParams. To see a complete working node, insert the macro by hand on any page and fetch it with GET /wiki/api/v2/pages/{id}?body-format=atlas_doc_format.
To create a page with a diagram already in it, POST /wiki/api/v2/pages with body.representation: "atlas_doc_format" and include this node in the ADF content array. The extensionKey and extensionId values identify the app itself and are the same on every install, so you can use them verbatim:
{
"type": "extension",
"attrs": {
"extensionType": "com.atlassian.ecosystem",
"extensionKey": "5bc0f2ac-dc58-48e4-a6f3-72a04868af63/f588a647-291e-4a44-b053-24107662a91c/static/mermaid-diagram-macro",
"parameters": {
"guestParams": {
"display": "diagram",
"source": "flowchart TD\n A[Draft] --> B[Review]\n B --> C[Publish]"
},
"forgeEnvironment": "PRODUCTION",
"extensionId": "ari:cloud:ecosystem::extension/5bc0f2ac-dc58-48e4-a6f3-72a04868af63/f588a647-291e-4a44-b053-24107662a91c/static/mermaid-diagram-macro",
"extensionTitle": "Mermaid Diagram"
}
}
}| Parameter | Values | What it does |
|---|---|---|
source | Mermaid text | The diagram source. Newlines as \n in JSON. |
display | diagram · source · both | Show the rendered diagram, the code, or both. Default diagram. |
style | style key, e.g. clean, boardroom | Visual style. Pro styles render on subscribed sites; others fall back to Clean. |
height | 300 · 450 · 600 | Diagram area height in px. Omit for automatic. |
fit | on | Open the diagram at the scale the Fit button gives, instead of the smaller default. Pairs well with height for wide flowcharts. |
exports | off | Hide the Export menu (Copy/Download SVG and PNG) under the diagram. Expand stays. |
elk | on · off | Right-angle connector routing (Pro). Omit to follow the style's default. |
Omitted parameters use their defaults, exactly as if left untouched in the edit dialog, and app versions that predate a parameter simply ignore it, so setting fit or exports is always safe. The FAQ below has a step-by-step for creating a page with a pre-filled diagram.
FAQ
My diagram isn't rendering. What should I check?
Open the macro editor: the live preview shows the exact error and highlights the offending line. The most common cause is a missing diagram-type declaration on the first line (e.g. flowchart TD). If you drafted in the Mermaid Live Editor, you can paste its share link straight into the editor to import the diagram.
Do diagrams appear when I export a page?
Yes. PDF exports include your diagrams fully rendered, with no app controls in the output. Word exports include the diagram source as a readable code block (Word's export pipeline can't render scripts, so the source is the most useful representation).
I pasted a mermaid code block. Why doesn't it render?
A plain mermaid code block stays plain text in Confluence, because the app never scans your page content (which is exactly why it can run with zero permissions). Insert the Mermaid Diagram macro instead (type /Mermaid in the editor) and paste your source there. It renders as a live diagram.
Why can't I drag the diagram bigger, the way I can with an image?
Confluence gives drag-resize handles to native images only; app macros don't get them, which is why no Mermaid app for Confluence offers dragging. It is a platform limitation rather than something we can switch on. Two things do work: the Expand button under any diagram opens a full-page view with zoom and pan, and the macro's edit dialog has a Diagram area height setting (Auto, 300, 450 or 600px) that is saved with the page for everyone who reads it. For a diagram wider than the content column, Expand is the one that helps most.
Why doesn't my diagram show inside an Include Page macro?
Confluence currently doesn't render any Marketplace app macros inside Include Page: the included content shows a placeholder instead of the app's output. This is a platform limitation that affects every diagram app, not something specific to Mermaid Macros. Diagrams render normally on the source page itself, and inside Expand sections.
How is this different from the Jira app?
The Confluence app uses a macro you insert via /Mermaid in the page editor, while Mermaid Diagrams for Jira automatically detects mermaid code blocks in issue descriptions and comments. The difference reflects how each product's editor works.
Does the app modify my Confluence content?
No. The app requests zero data-access permissions (an empty scope set), so it cannot read, create, or modify any page content. The macro only renders the Mermaid source you enter into it.
Can I create pages with diagrams via the REST API or MCP?
Yes. The macro is stored as a standard ADF extension node, so anything that can create a Confluence page can include a pre-filled diagram. Create the page with body-format=atlas_doc_format and put your Mermaid source in parameters.guestParams.source (newlines escaped as \n). To get the exact node, insert the macro by hand on any page once and fetch that page with GET /wiki/api/v2/pages/{id}?body-format=atlas_doc_format. The extensionKey and extensionId you'll see are the same on every install, so you can copy them into templates and scripts. Editing works the same way in reverse: fetch the page as ADF, change guestParams.source, and PUT it back. MCP tools that write Confluence pages can emit the same node.
Is the app free? What does Pro add?
Version 3 is free forever, for teams of any size; sites that stay on v3 keep everything they have. Updating to v4 starts a subscription: $0 for teams of 10 or under, paid above that. Pro styling is included with every subscription (nine designed styles saved with the macro, plus right-angle connectors), and no core feature has been moved behind it. Current pricing is on the app's Atlassian Marketplace pricing tab.
Is my data sent to external servers?
No. Rendering happens entirely in your browser, and the app itself never calls any service outside Atlassian: no analytics, no tracking, nothing phones home. Your diagram source stays in Confluence unless you deliberately take it somewhere: exporting a page, for example, is generated inside Atlassian and lands on your own device. See our Security Statement for details.
Support
Need help? Reach out to us: