Skip to main content

Mermaid Syntax Cheat Sheet for Confluence: Top 15 FAQ

· 12 min read
NGPilot
NGPilot
NGPilot

Mermaid has become the go-to diagramming language for Confluence teams who want to create flowcharts, sequence diagrams, class diagrams, and more without leaving their wiki pages. But even experienced users sometimes forget the exact syntax for a specific node shape or arrow style.

This FAQ-style cheat sheet covers the most common Mermaid syntax questions Confluence users ask. Whether you are building your first flowchart or debugging a complex diagram that will not render, you will find the answer here, along with ready-to-copy examples you can paste directly into your Confluence page.

Why a Mermaid Syntax Cheat Sheet Matters for Confluence Users​

Confluence supports Mermaid diagrams natively through macros, and third-party apps like Mermaid Plus for Confluence extend that support with additional features. The advantage of text-based diagramming is clear: your diagrams live alongside your documentation, version-controlled and easy to update.

The challenge is that Mermaid has its own syntax rules, and unlike visual drag-and-drop tools, you need to type the correct keywords and operators to get the output you want. A single misplaced bracket or missing colon can prevent a diagram from rendering entirely.

This guide is organized as a quick-reference FAQ so you can jump straight to the syntax question you need answered, then get back to work.

Frequently Asked Questions​

1. How do I create a flowchart in Mermaid?​

Flowcharts are the most popular Mermaid diagram type. Start with the flowchart keyword followed by a direction indicator:

  • TD or TB -- top-down (top to bottom)
  • BT -- bottom to top
  • LR -- left to right
  • RL -- right to left

Then define nodes and connections:

flowchart TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Process Action]
  B -->|No| D[End]
  C --> D

The direction keyword controls the overall layout. Every node is referenced by an ID (like A, B, C) and you define its shape with brackets around the label text.

2. How do I add text labels to Mermaid arrows?​

Labels on arrows make your diagrams self-documenting. Use the pipe | character immediately after the arrow operator:

flowchart LR
  A[Submit Request] -->|Approved| B[Process Payment]
  A -->|Rejected| C[Notify Customer]

For longer labels that contain special characters, wrap the label text in double quotes:

flowchart LR
  A -->|"Long label with (special) characters"| B

You can also place labels on the arrow using the -- text --> syntax:

flowchart LR
  A -- Review needed --> B

3. How do I create subgraphs in Mermaid?​

Subgraphs group related nodes together visually with a bordered box. Use the subgraph keyword, indent the grouped content, and close with end:

flowchart TB
  subgraph Frontend
    A[UI Layer] --> B[State Management]
  end
  subgraph Backend
    C[API Gateway] --> D[Service Layer]
  end
  B --> C

You can also give a subgraph a display title and control its direction independently:

flowchart TB
  subgraph Auth["Authentication Module"]
    direction LR
    E[Login] --> F[Token Validation]
    F --> G[Session]
  end

4. How do I style nodes with different shapes?​

Mermaid uses different bracket types to control node shapes. Here is a comprehensive reference:

flowchart LR
  A[Rounded Rectangle]
  B([Stadium / Pill Shape])
  C[[Subroutine]]
  D[(Database Cylinder)]
  E((Circle))
  F>Asymmetric Flag]
  G{Diamond / Decision}
  H{{Hexagon}}
Bracket SyntaxShapeTypical Use
[text]Rounded rectangleStandard process step
([text])Stadium / pillStart or end terminal
[[text]]SubroutineReusable process
[(text)]CylinderDatabase or data store
((text))CircleJunction or connector
>text]AsymmetricManual input or output
{text}DiamondDecision point
{{text}}HexagonPreparation step

5. What is the correct syntax for a sequence diagram?​

Sequence diagrams show interactions between participants over time. Start with the sequenceDiagram keyword:

sequenceDiagram
  participant User
  participant Frontend
  participant API
  participant DB

  User->>Frontend: Submit form
  Frontend->>API: POST /api/orders
  API->>DB: INSERT query
  DB-->>API: Confirmation
  API-->>Frontend: 201 Created
  Frontend-->>User: Success message

Key arrow types for sequence diagrams:

  • ->> solid line with arrowhead (synchronous request)
  • -->> dashed line with arrowhead (response or return)
  • --) solid line with open arrow (asynchronous message)
  • --) dashed line with open arrow (asynchronous return)

Add notes to clarify specific steps:

sequenceDiagram
  participant A as Client
  participant B as Server
  Note over A: User initiates request
  A->>B: GET /data
  Note over A,B: TLS encrypted
  B-->>A: JSON response

6. How do I create an ER diagram in Mermaid?​

Entity-relationship diagrams use the erDiagram keyword. Define entities with their attributes and relationships between them:

erDiagram
  CUSTOMER ||--o{ ORDER : "places"
  ORDER ||--|{ LINE_ITEM : "contains"
  CUSTOMER {
    int id PK
    string name
    string email
    date created_at
  }
  ORDER {
    int id PK
    int customer_id FK
    date order_date
    string status
  }
  LINE_ITEM {
    int id PK
    int order_id FK
    string product_name
    int quantity
    float price
  }

Relationship notation uses these operators:

SymbolMeaning
||Exactly one
o{Zero or more
||--o{One to zero-or-more
||--|{One to one-or-more
||--||One to one

7. How do I create a class diagram in Mermaid?​

Class diagrams use the classDiagram keyword. Define classes with their attributes, methods, and relationships:

classDiagram
  class Animal {
    +String name
    +int age
    +makeSound() void
    +move() void
  }
  class Dog {
    +String breed
    +fetch() void
    +bark() void
  }
  class Cat {
    +bool indoor
    +purr() void
    +scratch() void
  }
  Animal <|-- Dog
  Animal <|-- Cat

Visibility modifiers:

  • + public
  • - private
  • # protected

Relationship types include <|-- (inheritance), *-- (composition), o-- (aggregation), --> (association), and ..> (dependency).

8. How do I create a Gantt chart in Mermaid?​

Gantt charts visualize project schedules using the gantt keyword:

gantt
  title Project Timeline
  dateFormat YYYY-MM-DD
  axisFormat %b %d

  section Planning
    Requirements gathering  :done, req, 2026-05-01, 10d
    Architecture design     :active, arch, after req, 5d

  section Development
    Frontend implementation :dev-fe, after arch, 15d
    Backend API             :dev-be, after arch, 12d
    Integration testing     :test, after dev-fe, 7d

  section Deployment
    Staging release         :stage, after test, 3d
    Production release      :prod, after stage, 2d

Task states include done, active, and (default) future tasks. You can set task dependencies using after followed by the task ID.

9. How do I add comments in Mermaid syntax?​

Comments use the %% prefix and are ignored during rendering:

flowchart LR
  %% This is a comment and will not appear in the diagram
  A[Start] --> B[End]
  %% You can also comment out lines for debugging
  %% A --> C[Hidden node]

Comments are useful for leaving notes for collaborators or temporarily disabling parts of a diagram during editing.

10. How do I style Mermaid diagrams with custom colors?​

Use the style keyword to apply CSS-like properties to specific nodes:

flowchart LR
  A[Start] --> B[Process] --> C[End]
  style A fill:#4CAF50,stroke:#2E7D32,color:#fff
  style B fill:#2196F3,stroke:#1565C0,color:#fff
  style C fill:#f44336,stroke:#c62828,color:#fff

For reusable styles, define class definitions with classDef:

flowchart LR
  A[Start] --> B[Process] --> C[End]
  classDef green fill:#e8f5e9,stroke:#4CAF50,stroke-width:2px
  classDef blue fill:#e3f2fd,stroke:#2196F3,stroke-width:2px
  class A green
  class B,C blue

11. How do I use Mermaid diagrams in Confluence?​

In Confluence, you can add Mermaid diagrams using the built-in Mermaid macro or through apps like Mermaid Plus for Confluence:

  1. Open a Confluence page in edit mode
  2. Type /mermaid and select the Mermaid macro
  3. Paste your Mermaid code into the macro body
  4. Save or preview the page to see the rendered diagram

The Mermaid Plus app provides additional features like diagram templates, customizable themes, and output size controls. See the Mermaid Plus for Confluence usage guide for detailed instructions.

12. How do I create a pie chart in Mermaid?​

Pie charts use the pie keyword:

pie title Market Share by Region
  "North America" : 35
  "Europe" : 28
  "Asia Pacific" : 25
  "Latin America" : 8
  "Other" : 4

The values are treated as relative proportions. Mermaid calculates the percentages automatically based on the total.

13. How do I create a state diagram in Mermaid?​

State diagrams use the stateDiagram-v2 keyword (the v2 version supports more features):

stateDiagram-v2
  [*] --> Idle
  Idle --> Processing : Start
  Processing --> Success : Complete
  Processing --> Error : Failure
  Error --> Idle : Retry
  Success --> [*]

Use [*] to denote the start and end states. Add labels to transitions with a colon after the target state.

14. How do I create a mind map in Mermaid?​

Mind maps are supported in Mermaid v9.3 and later using the mindmap keyword:

mindmap
  root((Central Topic))
    Branch A
      Sub-topic A1
      Sub-topic A2
    Branch B
      Sub-topic B1
        Detail B1a
        Detail B1b
      Sub-topic B2
    Branch C
      Sub-topic C1

Indentation defines the hierarchy. Each level of indentation creates a deeper branch.

15. How do I troubleshoot Mermaid diagrams that do not render?​

When a Mermaid diagram fails to render in Confluence, check these common issues:

  • Missing keyword: Every diagram must start with a valid keyword (flowchart, sequenceDiagram, erDiagram, etc.)
  • Incorrect indentation: Some diagram types are sensitive to indentation, especially subgraphs and class definitions
  • Special characters in labels: Wrap labels containing special characters in double quotes
  • Trailing whitespace: Extra spaces at the end of lines can sometimes cause parsing errors
  • Unsupported features: Confluence may use an older version of Mermaid that does not support newer features like mind maps

For a comprehensive troubleshooting guide, see Mermaid Not Rendering? Fixes and FAQ.

Quick Syntax Reference​

ElementSyntaxExample
Flowchartflowchart TD/LRflowchart TD
Sequence diagramsequenceDiagramsequenceDiagram
Class diagramclassDiagramclassDiagram
ER diagramerDiagramerDiagram
Gantt chartganttgantt
State diagramstateDiagram-v2stateDiagram-v2
Pie chartpiepie title Sales
Mind mapmindmapmindmap
Arrow with label`-->text
Dashed arrow-.->A -.-> B
Thick arrow==>A ==> B
Subgraphsubgraph Name ... endsubgraph Auth\n A --> B\nend
Comment%% text%% This is a comment
Node stylestyle ID fill:#hexstyle A fill:#4CAF50
Rounded rectangleA[text]A[Start]
Diamond / decisionA{text}B{Choice?}
CircleA((text))C((Merge))
Database cylinderA[(text)]DB[(Database)]

Copy-Paste Examples​

Below are five complete, ready-to-use Mermaid diagrams. Copy any of these into a Confluence Mermaid macro and modify the content to match your needs.

Flowchart: User Registration Process​

flowchart TD
  A([User visits signup page]) --> B[Fill registration form]
  B --> C{Valid input?}
  C -->|Yes| D[Create account]
  C -->|No| E[Show validation errors]
  E --> B
  D --> F{Email verification?}
  F -->|Verified| G[Activate account]
  F -->|Pending| H[Send reminder email]
  H --> I{Max retries?}
  I -->|No| H
  I -->|Yes| J[Deactivate account]
  G --> K([User logged in])

This flowchart covers a complete user registration flow with form validation, email verification, and retry logic. Adapt the decision points and actions for your own registration workflow.

Sequence Diagram: API Authentication Flow​

sequenceDiagram
  participant Client
  participant AuthServer as Auth Server
  participant ResourceServer as Resource Server
  participant Cache as Redis Cache

  Client->>AuthServer: POST /oauth/token (credentials)
  AuthServer->>Cache: Check existing session
  Cache-->>AuthServer: No active session
  AuthServer->>AuthServer: Validate credentials
  AuthServer-->>Client: Access token + Refresh token
  Note over Client: Store tokens securely

  Client->>ResourceServer: GET /api/data (Bearer token)
  ResourceServer->>AuthServer: Validate token
  AuthServer-->>ResourceServer: Token valid
  ResourceServer-->>Client: 200 OK + JSON data

  Note over Client,AuthServer: After token expires
  Client->>AuthServer: POST /oauth/token (refresh token)
  AuthServer-->>Client: New access token

Class Diagram: E-Commerce Order System​

classDiagram
  class User {
    +int id
    +String name
    +String email
    +login() bool
    +logout() void
  }

  class Order {
    +int id
    +Date createdAt
    +String status
    +calculateTotal() float
    +cancel() bool
  }

  class Product {
    +int id
    +String name
    +float price
    +int stock
    +reduceStock(qty: int) void
  }

  class Payment {
    +int id
    +float amount
    +String method
    +process() bool
    +refund() bool
  }

  class OrderItem {
    +int quantity
    +float unitPrice
    +getSubtotal() float
  }

  User "1" --> "*" Order : places
  Order "1" --> "*" OrderItem : contains
  OrderItem "*" --> "1" Product : references
  Order "1" --> "1" Payment : paid by

ER Diagram: Blog Platform Schema​

erDiagram
  AUTHOR ||--o{ POST : "writes"
  POST ||--o{ COMMENT : "receives"
  POST }o--|| CATEGORY : "belongs to"
  POST ||--o{ TAG_POST : "tagged with"
  TAG ||--o{ TAG_POST : "applied to"

  AUTHOR {
    int id PK
    string username
    string email
    string bio
    date joined_at
  }

  POST {
    int id PK
    int author_id FK
    int category_id FK
    string title
    text content
    string status
    date published_at
  }

  COMMENT {
    int id PK
    int post_id FK
    string author_name
    text body
    date created_at
  }

  CATEGORY {
    int id PK
    string name
    string slug
  }

  TAG {
    int id PK
    string name
    string slug
  }

  TAG_POST {
    int tag_id FK
    int post_id FK
  }

Gantt Chart: Software Release Timeline​

gantt
  title Software Release v2.0 Timeline
  dateFormat YYYY-MM-DD
  axisFormat %b %d

  section Design
    UX research           :done, ux, 2026-04-01, 7d
    Wireframes            :done, wire, after ux, 5d
    Visual design         :done, vis, after wire, 7d

  section Development
    Frontend sprint 1     :active, fe1, 2026-04-21, 10d
    Frontend sprint 2     :fe2, after fe1, 10d
    Backend API           :be, 2026-04-21, 14d
    Integration           :int, after fe2, 5d

  section Testing
    QA regression         :qa, after int, 7d
    UAT                   :uat, after qa, 5d
    Bug fixes             :fix, after uat, 5d

  section Release
    Staging deploy        :stage, after fix, 2d
    Production deploy     :prod, after stage, 1d
    Post-release monitor  :mon, after prod, 5d

Tips for Using Mermaid in Confluence​

Keep diagrams focused. A single diagram should tell one story. If your flowchart has more than 15 nodes, consider splitting it into multiple diagrams with linking subgraphs.

Use consistent naming. Adopt a naming convention for your node IDs (like step1, step2 or A, B, C) and stick with it across your team's diagrams. This makes collaboration and code reviews much easier.

Test incrementally. When building complex diagrams, add a few nodes at a time and preview after each addition. This makes it much easier to spot the exact change that broke the rendering.

Leverage templates. If your team creates similar diagrams repeatedly (onboarding flows, deployment pipelines, API interactions), save the Mermaid code as a Confluence template so everyone starts from a consistent baseline.

Version your diagrams. Since Mermaid is text-based, Confluence's page history captures every change. Use meaningful commit messages when updating complex diagrams so your team can track what changed and why.