How to Add Mermaid.js Diagrams to Confluence

Why Use Mermaid.js in Confluence?

Confluence is one of the most widely used documentation platforms in enterprise teams. Its built-in diagramming tools (Gliffy, Draw.io) create binary files that are hard to version-control, diff, or update without reopening a visual editor.

Mermaid.js changes that. Write plain text, get a rendered diagram. Updates take seconds, not minutes. And because the source is text, you can copy-paste it anywhere — GitHub, Notion, VS Code, your docs site.

This guide covers every method to add Mermaid diagrams to Confluence.

Method 1: Marketplace App (Confluence Cloud — Easiest)

For Confluence Cloud, the fastest path is a marketplace app. Search for "Mermaid" in the Atlassian Marketplace — several free and paid options are available.

Installation:

1. Go to Confluence Settings → Find new apps
2. Search for "Mermaid Diagrams" or "Markdown Macro"
3. Install your chosen app
4. On any page, insert /mermaid or {mermaid} macro
5. Paste your Mermaid syntax
6. Save — the diagram renders inline

Method 2: HTML Macro (Data Center / Server)

For Confluence Data Center or Server, use the HTML Macro (if your admin has enabled it). This loads Mermaid.js via CDN client-side.

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<div class="mermaid">
graph TD
    A[Product Backlog] --> B[Sprint Planning]
    B --> C[Sprint Execution]
    C --> D[Sprint Review]
    D --> E[Retrospective]
    E --> B
</div>
<script>mermaid.initialize({ startOnLoad: true });</script>

> The HTML macro must be enabled by a Confluence administrator.

Method 3: Export as Image (Universal Fallback)

Works in every Confluence version, no admin permission needed:

1. Build your diagram at MermaidEditor.lol
2. Export as PNG or SVG
3. Upload the image to Confluence
4. Add a collapsible code block with the raw Mermaid source for future edits

This gives you a visual diagram now, with the source preserved for later.

Real-World Examples

System Architecture

graph TB
    subgraph Cloud
        LB[Load Balancer]
        subgraph App Tier
            A1[API Server 1]
            A2[API Server 2]
        end
        subgraph Data Tier
            DB[(Primary DB)]
            CACHE[Redis]
        end
    end
    USERS[Users] --> LB
    LB --> A1 & A2
    A1 & A2 --> DB & CACHE

Incident Response Flow

graph TD
    ALERT[Alert Triggered] --> SEV{Severity?}
    SEV -- P1/P2 --> PAGE[Page On-Call]
    SEV -- P3/P4 --> TICKET[Create Ticket]
    PAGE --> ACK[Acknowledge 15min]
    ACK --> INV[Investigate]
    INV --> RES{Resolved?}
    RES -- Yes --> PIR[Post-Incident Review]
    RES -- No --> ESC[Escalate to Lead]
    ESC --> INV
    PIR --> RUNBOOK[Update Runbook]

Agile Sprint States

stateDiagram-v2
    [*] --> Backlog
    Backlog --> InProgress : Sprint Start
    InProgress --> InReview : Dev Complete
    InReview --> Done : Approved
    InReview --> InProgress : Changes Requested
    Done --> [*]

Tips for Teams

• Create a Confluence template with placeholder Mermaid diagrams for common doc types (architecture, runbook, RFC)
• Always include source — even when using screenshots, add the Mermaid code in a collapsed section
• Name pages clearly — "Architecture: Payment Service v2" beats "Payment Diagram"
• Update diagrams in the same session as the system changes they describe

Conclusion

Mermaid.js brings diagrams-as-code to Confluence. Whether you use a marketplace macro, the HTML macro, or the screenshot workflow, your team can have clean, maintainable technical diagrams in the knowledge base.

The real win: diagrams become living documentation that evolves with your codebase.

Create and export Mermaid diagrams for free →