Mermaid Flowchart Guide

Syntax, shapes, arrows, and copy-paste examples for Markdown

Basic Flowchart

A Mermaid flowchart starts with graph or flowchart followed by a direction. The most common directions are TD (top-down) and LR (left-to-right).

Mermaid ```mermaid graph TD A[Start] --> B[Process] B --> C[End] ```
Basic Mermaid flowchart: Start, Process, End connected by arrows

This creates three rectangular nodes connected by arrows, flowing from top to bottom.

Flow Directions

  • TD or TB — top to bottom (vertical, default)
  • LR — left to right (horizontal)
  • BT — bottom to top
  • RL — right to left

Use TD for decision trees and process flows. Use LR for pipelines, CI/CD workflows, and timelines.

Mermaid ```mermaid graph LR Push --> Build --> Test --> Deploy ```
Mermaid left-to-right pipeline: Push, Build, Test, Deploy

Node Shapes

Different shapes convey different meanings in flowcharts:

Mermaid ```mermaid graph TD A[Rectangle] --> B(Rounded) B --> C{Diamond} C --> D((Circle)) C --> E>Asymmetric] E --> F{{Hexagon}} ```
Mermaid node shapes: rectangle, rounded, diamond, circle, asymmetric
  • [text] — rectangle (process step)
  • (text) — rounded rectangle (start/end)
  • {text} — diamond (decision)
  • ((text)) — circle (connector)
  • >text] — asymmetric (flag/event)
  • {{text}} — hexagon (preparation)

Arrow Types

Mermaid ```mermaid graph LR A -->|solid arrow| B C -.->|dotted arrow| D E ==>|thick arrow| F G --- H ```
  • --> — solid arrow
  • -.-> — dotted arrow
  • ==> — thick arrow
  • --- — line without arrow
  • -->|text| — arrow with label

Decision Trees

Use diamond shapes for decisions and labeled arrows for outcomes:

Mermaid ```mermaid graph TD A[User submits form] --> B{Valid?} B -->|Yes| C[Save to database] B -->|No| D[Show errors] D --> A C --> E[Send confirmation email] E --> F[Done] ```

Subgraphs

Group related nodes into named sections:

Mermaid ```mermaid graph LR subgraph Frontend A[React App] --> B[API Client] end subgraph Backend C[Express Server] --> D[Database] end B --> C ```

Subgraphs draw a labeled border around a group of nodes. They’re useful for showing system boundaries in architecture diagrams.

CI/CD Pipeline Example

A real-world example — a CI/CD pipeline with stages and decisions:

Mermaid ```mermaid graph LR A[Push to main] --> B[Build] B --> C[Run tests] C --> D{Tests pass?} D -->|Yes| E[Deploy to staging] D -->|No| F[Notify team] E --> G{Approved?} G -->|Yes| H[Deploy to production] G -->|No| I[Rollback] ```
Mermaid CI/CD pipeline with build, test, deploy stages and decision points

Tips

  • Keep node IDs short (A, B, C) and put readable text in brackets
  • Use LR for pipelines and TD for decision trees
  • Break complex diagrams into subgraphs
  • Label decision arrows with |Yes| and |No|
  • Use flowchart instead of graph for newer Mermaid features

For more Mermaid diagram types, see What Is Mermaid? and Mermaid Sequence Diagrams.

View Flowcharts with MDViewer

MDViewer renders Mermaid flowcharts as interactive SVGs — zoom, pan, and full-screen. Paste any example from this guide into a .md file and open it.

Download MDViewer

Requires macOS 13.0 or later. Intel and Apple Silicon.