5 min read

A Mermaid Cheat Sheet for Jira and Confluence

The Mermaid syntax you’ll actually use — flowcharts, sequence diagrams, ERDs, Gantt charts, and state diagrams — with copy-paste examples that render right inside Jira and Confluence.

Mermaid lets you write diagrams as plain text — which means they live next to your work, diff cleanly, and never require hunting down the one person with the drawing tool license. With Mermaid Diagrams for Jira you just write a ```mermaid code block in any issue or comment; in Confluence, Mermaid Macros for Confluence adds a /Mermaid macro to the editor. Either way, here's the syntax you'll reach for most.

Flowcharts

The workhorse. TD flows top-down; use LR for left-to-right. Square brackets make boxes, braces make decisions, and --> draws arrows (with optional |labels|).

flowchart TD
    A[Ticket created] --> B{Reproducible?}
    B -->|yes| C[Fix it]
    B -->|no| D[Request more info]
    D --> B
    C --> E[Code review]
    E --> F[Ship]

Sequence diagrams

Perfect for API flows and incident writeups. Solid arrows (->>) are requests, dashed (-->>) are responses.

sequenceDiagram
    participant U as User
    participant A as API
    participant D as Database
    U->>A: POST /orders
    A->>D: INSERT order
    D-->>A: order id
    A-->>U: 201 Created

Entity-relationship diagrams

Great for data-model discussions on architecture pages. The symbols read as “one” (||) and “many” (o{).

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "ordered in"

Gantt charts

Lightweight roadmaps without a project-management tool:

gantt
    title Release plan
    dateFormat YYYY-MM-DD
    axisFormat %b %d
    tickInterval 1week
    section Build
    API work        :a1, 2026-07-06, 3w
    Frontend        :a2, after a1, 2w
    section Launch
    Beta            :b1, after a2, 1w
    GA              :milestone, after b1, 0d

State diagrams

Document a workflow's legal transitions — ideal for Jira workflow discussions:

stateDiagram-v2
    [*] --> Open
    Open --> InProgress : assign
    InProgress --> InReview : PR ready
    InReview --> InProgress : changes requested
    InReview --> Done : approved
    Done --> [*]

Six tips that save the most time

  • Tame gantt date labels. By default the axis prints full dates (2026-07-01) at every other day, and they collide on narrow charts. Add axisFormat %b %d and tickInterval 1week for clean weekly ticks like Jul 05.
  • Quote labels with special characters. A["Deploy (prod)"] — parentheses and brackets inside unquoted labels are the #1 syntax error.
  • Name your participants. participant A as API keeps sequence diagrams short to type but readable to everyone else.
  • Prefer several small diagrams over one giant one. A diagram that needs horizontal scrolling in an issue has stopped communicating.
  • Use direction to fit the space. Wide pages like Confluence suit flowchart LR; narrow issue panels suit TD.
  • Prototype in the Mermaid live editor. Paste into mermaid.live to iterate fast, then drop the final source into your issue or page.