/mermaid-diagrams

Flowchart Diagrams

Flowcharts visualize processes, algorithms, and decision flows using nodes and edges.

Contents

• Basic Syntax
• Direction
• Node Shapes
• Edge Types
• Subgraphs
• Multi-Target Edges
• Markdown in Labels
• Icons
• Click Events
• Styling
• Layout Engine
• Gotchas
• Examples

Basic Syntax

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

Direction

flowchart TB
    A --> B --> C

Node Shapes

Standard Shapes

A[Rectangle]         Default box
B(Rounded)           Rounded corners
C([Stadium])         Pill shape
D[[Subroutine]]      Double vertical lines
E[(Database)]        Cylinder
F((Circle))          Circle
G{Diamond}           Decision/rhombus
H{{Hexagon}}         Hexagon
I[/Parallelogram/]   Slanted right
J[\Parallelogram\]   Slanted left
K[/Trapezoid\]       Trapezoid
L[\Trapezoid/]       Inverted trapezoid
M(((Double Circle))) Double circle

Extended Shapes (v11.3+)

New syntax using @{ shape: name }:

flowchart LR
    doc@{ shape: doc, label: "Document" }
    db@{ shape: cyl, label: "Database" }
    proc@{ shape: rect, label: "Process" }
    dec@{ shape: diamond, label: "Decision" }

Available extended shapes:

Edge Types

Basic Edges

A --> B       Solid arrow
A --- B       Solid line (no arrow)
A -.-> B      Dotted arrow
A -.- B       Dotted line
A ==> B       Thick arrow
A === B       Thick line

Arrow Ends

A --o B       Circle end
A --x B       Cross end
A o--o B      Circle both ends
A x--x B      Cross both ends
A <--> B      Arrows both ends

Edge Labels

flowchart LR
    A --> |label| B
    C -- text --> D
    E -->|"multi word"| F

Edge Length

Control edge length with extra dashes:

A --> B        Normal
A ---> B       Longer
A ----> B      Even longer

Edge IDs and Animation (v11+)

flowchart LR
    A e1@--> B e2@--> C
    e1@{ animate: true }
    e2@{ animate: true, animation-duration: "0.5s" }

Subgraphs

Group related nodes:

flowchart TB
    subgraph Frontend
        UI[React App]
        State[Redux Store]
    end

    subgraph Backend
        API[REST API]
        WS[WebSocket]
    end

    subgraph Data
        DB[(PostgreSQL)]
        Cache[(Redis)]
    end

    UI --> API
    UI --> WS
    API --> DB
    API --> Cache

Nested Subgraphs

flowchart TB
    subgraph Cloud
        subgraph VPC
            subgraph Public
                LB[Load Balancer]
            end
            subgraph Private
                App[App Server]
                DB[(Database)]
            end
        end
    end

    LB --> App --> DB

Subgraph Direction

flowchart LR
    subgraph TOP
        direction TB
        A --> B
    end
    subgraph BOTTOM
        direction TB
        C --> D
    end
    TOP --> BOTTOM

Multi-Target Edges

Connect multiple nodes:

flowchart LR
    A --> B & C --> D
    E & F --> G

Markdown in Labels

Use backticks for markdown:

flowchart LR
    A["`**Bold** and *italic*`"]
    B["`Multi
    line
    text`"]
    A --> B

Icons

FontAwesome icons (when enabled):

flowchart LR
    A[fa:fa-user User] --> B[fa:fa-database Database]
    B --> C[fa:fa-cog Settings]

Click Events

Links

flowchart LR
    A[GitHub] --> B[Docs]
    click A href "https://github.com" _blank
    click B href "https://docs.example.com"

Callbacks

flowchart LR
    A[Click Me] --> B
    click A call callback()

Styling

Inline Styles

flowchart LR
    A[Start]:::green --> B[Process]:::blue --> C[End]:::green

    classDef green fill:#10b981,stroke:#059669,color:white
    classDef blue fill:#3b82f6,stroke:#2563eb,color:white

Individual Node Style

flowchart LR
    A --> B --> C
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333

Link Styles

flowchart LR
    A --> B --> C
    linkStyle 0 stroke:red,stroke-width:2px
    linkStyle 1 stroke:blue,stroke-width:2px,stroke-dasharray:5

Default Styles

flowchart LR
    A --> B --> C
    linkStyle default stroke:gray,stroke-width:1px

Layout Engine

Use ELK for complex diagrams (v9.4+):

%%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%
flowchart TB
    A --> B & C & D
    B & C & D --> E

Gotchas

• end is reserved. A lowercase node ID or label end breaks parsing because it terminates subgraphs. Use End, stop, or wrap it: e[end].
• o and x after an edge are arrow heads. A---oB parses as a circle-ended edge to B, not an edge to node oB. Add a space (A--- oB) or capitalize the node ID.
• Node IDs must not collide with subgraph IDs. A node Build inside subgraph Build throws "would create a cycle". Use a distinct ID with display text in brackets: Compile[Build].
• Quote labels containing special characters. Parentheses, brackets, colons, or leading digits inside unquoted labels break parsing: use A["Fetch (retry)"]. Escape literal quotes/hashes inside quoted labels with #quot; and #35;.
• Comments are %% on their own line, not // or #.

Examples

Microservices Architecture

flowchart LR
    subgraph Client
        Web[Web App]
        Mobile[Mobile App]
    end

    subgraph Gateway
        Kong[API Gateway]
        Auth[Auth Service]
    end

    subgraph Services
        Users[Users Service]
        Orders[Orders Service]
        Products[Products Service]
        Payments[Payments Service]
    end

    subgraph Data
        UsersDB[(Users DB)]
        OrdersDB[(Orders DB)]
        ProductsDB[(Products DB)]
        MQ[Message Queue]
    end

    Web & Mobile --> Kong
    Kong --> Auth
    Auth --> Users
    Kong --> Orders & Products & Payments
    Users --> UsersDB
    Orders --> OrdersDB
    Products --> ProductsDB
    Orders --> MQ
    Payments --> MQ

CI/CD Pipeline

flowchart LR
    subgraph Source
        Git[Git Push]
    end

    subgraph Build
        Lint[Lint]
        Test[Test]
        Compile[Build]
    end

    subgraph Deploy
        Staging[Staging]
        Prod[Production]
    end

    Git --> Lint --> Test --> Compile
    Compile --> Staging
    Staging -->|approved| Prod

    style Prod fill:#10b981

Decision Tree

flowchart TD
    Start[User Request] --> Auth{Authenticated?}
    Auth -->|Yes| Perm{Has Permission?}
    Auth -->|No| Login[Redirect to Login]
    Perm -->|Yes| Process[Process Request]
    Perm -->|No| Denied[403 Forbidden]
    Process --> Success[200 OK]

    style Success fill:#10b981
    style Denied fill:#ef4444
    style Login fill:#f59e0b

Data Flow

flowchart LR
    Input[(Raw Data)] --> Transform[ETL Process]
    Transform --> Validate{Valid?}
    Validate -->|Yes| Store[(Data Warehouse)]
    Validate -->|No| Error[Error Queue]
    Store --> Analytics[Analytics Engine]
    Analytics --> Dashboard[Dashboard]
    Analytics --> Reports[Reports]