A 10-Minute Guide to Mermaid Flowcharts

Flowcharts are the bread and butter of technical documentation. They map out user journeys, decision trees, and system logic. In this quick guide, we'll learn how to create powerful flowcharts using Mermaid syntax.

1. Defining the Direction

Every Mermaid flowchart starts with the flowchart keyword followed by the direction. TD means Top-Down, while LR means Left-Right.

flowchart TD
  A --> B

2. Node Shapes

The shape of a node is determined by the brackets you use around its text:

• [Rectangle] - Standard process step.
• (Rounded Rectangle) - Often used for start/end points.
• {Rhombus} - Used for decisions or conditions.
• ((Circle)) - Used for states or smaller connection nodes.

3. Connectors and Labels

Connecting nodes is simple. You use arrows. You can also add text labels to these arrows to explain the relationship.

flowchart LR
  A[Start] --> B{Is it valid?}
  B -->|Yes| C[Process Data]
  B -->|No| D[Reject Request]

4. Subgraphs

To group related nodes together, you can use subgraphs. This is incredibly useful for showing different system components or bounded contexts.

flowchart TD
  subgraph Frontend
    UI[User Interface]
  end
  subgraph Backend
    API[API Gateway]
    DB[(Database)]
  end
  UI --> API
  API --> DB

With just these four basic concepts, you can build 90% of the flowcharts you'll ever need. Head over to the Mermaid Preview editor to try writing your first flowchart!