Mermaid Studio documentation

Everything you need to write, style, link and export diagrams in Confluence.

Open a Confluence page for editing, type /mermaid and choose Mermaid Diagram. The editor opens automatically.

You do not need to know the syntax to begin. Pick one of the examples along the top — Flowchart, Sequence, ERD, Gantt, Class, State, Pie or Mind map — and edit it. The preview updates as you type, and the Syntax reference panel underneath changes to match whichever diagram type you are working on.

Save stays disabled while a diagram has a syntax error, so a broken diagram never reaches the page.

The most common diagram type. Start with a direction:

flowchart LR
  A[Merge to main] --> B{Tests pass?}
  B -->|No| C[Notify author]
  B -->|Yes| D[Deploy]

LR lays the diagram out left to right; TD lays it out top down. Prefer TD for anything more than about six steps — Confluence pages are narrow, so tall diagrams read better than wide ones.

Node shapes:

A[Rectangle]
A(Rounded)
A([Stadium])
A{Decision}
A((Circle))
A[(Database)]

Connections:

A --> B      solid arrow
A --- B      line, no arrowhead
A -.-> B     dotted
A ==> B      thick
A -->|yes| B labelled

Sequence — who talks to whom, in order:

sequenceDiagram
  participant User
  participant API
  User->>API: POST /order
  API-->>User: 201 Created

Entity relationship — the symbols read as cardinality:

erDiagram
  CUSTOMER ||--o{ ORDER : places

|| exactly one · o| zero or one · }| one or many · }o zero or many

Gantt — dates need a format declared first:

gantt
  title Release plan
  dateFormat YYYY-MM-DD
  section Build
    Design  :done,   des1, 2026-08-01, 7d
    Develop :active, dev1, after des1, 14d

Each task is name :status, id, start, duration. Use after <id> instead of a date to chain tasks. :milestone marks a single point in time.

State — [*] is start and end:

stateDiagram-v2
  [*] --> Draft
  Draft --> Review : submit
  Review --> [*]

Class diagrams, pie charts, mind maps, user journeys, timelines, quadrant charts and git graphs all work too. The full syntax for every type is documented at mermaid.js.org.

The Colours menu sets a theme for the whole diagram. Auto follows Confluence's light or dark mode; the others stay fixed regardless of the reader's setting.

To colour individual nodes, add style lines at the end:

style A fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px

Or define a style once and reuse it:

classDef warn fill:#fee2e2,stroke:#dc2626
class A,B warn

Fixed node colours do not adapt to dark mode, so pick shades that work on both if your team uses it.

Any node can open a page:

flowchart LR
  A[Design] --> B[Build]
  click A "/wiki/spaces/DOCS/pages/12345"

Linked nodes are clickable and reachable by keyboard. Use a relative path for Confluence pages and a full URL for anything external. Only http and https links are permitted — a diagram cannot run scripts.

Hovering a published diagram reveals a toolbar in the top right.

• − / + / Fit — zoom, or scale to the page width
• Full screen — for diagrams that outgrow the page
• Copy — the diagram source, as text
• Image — the diagram as a PNG on your clipboard
• SVG / PNG — download the file

Ctrl or Cmd with the scroll wheel zooms as well. PNG exports at twice the display size so they stay sharp in slides.

Revert changes undoes edits made since you opened the editor. Restore a previous version goes back further — the last five saved versions of each diagram are kept with the page.

Restoring loads the older version into the editor without saving it, so you can look before committing.

The Alt text field describes the diagram to screen readers. Describe what the diagram shows rather than naming it — for example "Order flow from request through approval to shipment" rather than "Order diagram".

Errors name the line and point at the character. The most common causes:

• Missing diagram type — the first line must say what kind of diagram this is, such as flowchart LR
• Unmatched brackets — every [, { or ( needs its closing partner
• Reserved words as node names — end in particular; use End or done instead
• Special characters in labels — wrap the label in quotes: A["Cost (USD)"]

Worth knowing before you commit to it:

• PDF and Word export — Confluence does not currently render Forge app macros in exports. Download the diagram as PNG or SVG and place it in the document instead.
• Editing from the page — diagrams are edited through the macro editor. Confluence provides no way for an app to open its own configuration from the published page.

Both are platform constraints rather than choices. We will remove them when Atlassian makes it possible.

Email [email protected] with the diagram source and what you expected to happen. Response targets are in our service level agreement.