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.
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: your diagram source never leaves Confluence — rendering happens in the browser, and page exports are generated inside Atlassian.
- 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.
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 — 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 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.
Is my data sent to external servers?
No. All rendering happens in your browser — your diagram source never leaves Confluence. The app never communicates with any service outside Atlassian: no analytics, no tracking, nothing leaves your instance. See our Security Statement for details.
Support
Need help? Reach out to us: