Skip to main content

Mermaid Syntax Cheat Sheet — Copy-Paste Code for All 26 Diagram Types

· 13 min read
NGPilot
NGPilot
NGPilot

Mermaid is the most popular text-based diagramming language for technical documentation. One line of code generates a flowchart. A few more produce a sequence diagram, ER diagram, or Gantt chart. Teams using Confluence can embed Mermaid diagrams directly on their pages, keeping diagrams alongside the documentation they illustrate.

This cheat sheet covers every Mermaid diagram type, node shape, arrow style, and styling option. Every example is copy-paste ready — paste the code block into your Confluence page and customize it for your project.

How to Use This Cheat Sheet in Confluence​

To render Mermaid diagrams on your Confluence pages, you need a Mermaid macro. Here are three options, ranked by features:

  1. Mermaid Plus for Confluence — dedicated Mermaid editor with 26+ diagram types, live preview, templates, and customizable themes. Type /mermaid to insert the macro. Install from the Atlassian Marketplace.

  2. Diagram Duo for Confluence — combines a full Mermaid editor and an Excalidraw visual canvas in one macro. Best choice if your team uses both text-based and visual diagrams. Type /mermaid or /excalidraw on any page.

  3. Confluence built-in Mermaid macro — limited to basic diagram types with no template library or theme customization.

All examples on this page work with any of these options. Copy the code, paste it into the macro, and publish.

Quick Syntax Reference​

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?​

You have three options for rendering Mermaid diagrams in Confluence:

Mermaid Plus for Confluence (recommended) — dedicated Mermaid editor with 26+ diagram types, live preview, templates, and theme customization. Best if your team wants a focused Mermaid experience.

  1. Install Mermaid Plus from the Atlassian Marketplace
  2. Open a Confluence page in edit mode
  3. Type /mermaid and select the Mermaid Plus macro
  4. Paste your Mermaid code into the code editor
  5. Preview, save, and publish the page

Diagram Duo for Confluence — combines a Mermaid code editor with an Excalidraw visual canvas in one macro. Switch between text-based and visual diagramming on the same page. Type /mermaid or /excalidraw to insert.

Confluence built-in macro — supports basic diagram types with no template library or theme options. Good for getting started quickly.

All three options render the Mermaid syntax documented in this cheat sheet.

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)]

Frequently Asked Questions​

5 Copy-Paste Mermaid Diagrams​

These five diagrams cover the most common patterns teams need. Copy any of them into your Confluence Mermaid macro and customize the content.

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])

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.