Skip to main content

Create Mermaid diagrams in Confluence: a step-by-step guide

· 4 min read
NGPILOT

Mermaid is a compact, human-readable language for generating diagrams from text. This guide shows how to create common diagram types in Confluence, with ready-to-use examples you can paste into the Mermaid editor.

Quick prerequisites​

  • Confluence Cloud with Mermaid Plus (or Mermaid-enabled) app installed
  • Basic familiarity with Markdown-style editing in Confluence

How to insert a Mermaid diagram​

  1. Edit a Confluence page.
  2. Insert the Mermaid macro (type /mermaid and choose the plugin).
  3. Paste one of the examples below into the editor and preview.
  4. Adjust labels, colors, and sizes as needed, then save.

Best practices​

  • Start small and iterate: preview often while editing.
  • Use templates for repetitive diagrams.
  • Prefer simple node labels for readability.
  • Use theme and color settings for accessible contrast.

Full list of common Mermaid diagram types (with examples)​

Flowchart (graph)​

A directed graph for processes and workflows.

graph TD
  A[Start] --> B{Is it ok?}
  B -- Yes --> C[Proceed]
  B -- No --> D[Fix issue]
  D --> B
  C --> E[Done]

Sequence diagram (sequenceDiagram)​

Interaction over time between participants.

sequenceDiagram
  participant Alice
  participant Bob
  Alice->>Bob: Request data
  Bob-->>Alice: Return result
  Alice->>Bob: Acknowledge

Class diagram (classDiagram)​

Model object-oriented classes and relationships.

classDiagram
  class Animal {
    +int age
    +eat()
  }
  class Dog {
    +bark()
  }
  Animal <|-- Dog

State diagram (stateDiagram-v2)​

Finite state machine transitions.

stateDiagram-v2
  [*] --> Idle
  Idle --> Processing : start
  Processing --> Done : finish
  Done --> [*]

Entity-Relationship (erDiagram)​

Database entities and relations.

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE_ITEM : contains
  CUSTOMER {
    string name
    int id
  }

Gantt chart (gantt)​

Project timelines with tasks and dependencies.

gantt
  title Project Schedule
  dateFormat  YYYY-MM-DD
  section Design
  Research :a1, 2026-05-01, 10d
  Develop  :after a1, 20d
  Test     :2026-06-01, 10d

Pie chart (pie)​

Simple proportional data visualization.

pie title Time Allocation
  "Development" : 50
  "Testing" : 30
  "Meeting" : 20

Git graph (gitGraph)​

Visualize branch and commit history.

gitGraph
  commit
  branch develop
  checkout develop
  commit
  checkout main
  merge develop
  commit

Mindmap (mindmap)​

Hierarchical brainstorming diagrams.

mindmap
  root((Product))
    Features
      Performance
      UX
    Roadmap
      Q2
      Q3

Timeline (timeline)​

Chronological events.

timeline
  title Company milestones
  2019 : Founded
  2020 : First release
  2022 : Series A

Requirement diagram (requirementDiagram)​

Traceability of requirements to elements.

requirementDiagram
  requirement R1 {
    id: 1
    text: "Data export must support CSV"
  }
  element E1 {
    type: component
  }
  E1 - satisfies -> R1

C4 & Architecture (C4Context)​

High-level system context diagrams.

C4Context
  title System Context
  Person(user, "User")
  System(api, "Public API")
  Rel(user, api, "Uses")

Quadrant chart (quadrantChart)​

Two-axis analysis charts.

quadrantChart
  title Feature Analysis
  x-axis Low --> High
  y-axis Low --> High
  quadrant-1 Prioritize
  quadrant-2 Consider
  Item A: [0.7, 0.6]
  Item B: [0.2, 0.8]

Sankey diagram (sankey)​

Bulk flow volumes between nodes.

sankey
  A [Source] -> B [Target] : 100
  A -> C : 50
  C -> B : 30

XY chart (xychart)​

Line and bar charts for time-series or categorical data.

xychart
  title Revenue
  x-axis [Q1,Q2,Q3,Q4]
  y-axis "USD"
  line [30,40,50,60]

Block diagram (block)​

Simple block/column diagrams.

block
  A[Frontend] --> B[API]
  B --> C[Database]

Packet diagram (packet)​

Network packet structure.

packet
  0-15: Source Port
  16-31: Destination Port
  32-63: Sequence Number

Kanban (kanban)​

Board-style task flow.

kanban
  To Do
    Task A
  In Progress
    Task B
  Done
    Task C

Treemap (treemap)​

Hierarchical data as nested rectangles.

treemap
  "Category A"
    "Item 1" : 10
    "Item 2" : 20

Ishikawa / Fishbone (ishikawa)​

Cause-and-effect analysis.

ishikawa
  Problem: "Low throughput"
    People
      Lack of training
    Process
      Missing steps

Venn diagram (venn)​

Set relationships.

venn
  A
  B
  A & B

ZenUML (zenuml)​

Alternative sequence diagram syntax.

zenuml
  title Login Flow
  Actor User
  System API
  User -> API: login()

Troubleshooting & tips​

  • If diagrams don't render, check the plugin settings or try the Mermaid Live Editor to validate syntax.
  • Use small examples while iterating; large diagrams can be hard to edit inside Confluence.
  • For accessibility, prefer clear color contrasts and short labels.

Further reading and templates​

  • Full syntax reference: https://mermaid.js.org
  • Use the built-in Templates panel in Mermaid+ for Confluence to jump-start diagrams.