Mermaid Flowcharts: Nodes, Decisions, Labels, and Direction

A Mermaid flowchart is a text model of nodes and edges. The first line selects the diagram type and direction. flowchart TD runs from top to bottom; flowchart LR runs from left to right. Choose the direction based on the story rather than available screen space.

Separate node identity from its label

Use a short, stable ID and put the human-readable text in brackets:

flowchart LR
  request[Receive request] --> validate{Input valid?}
  validate -->|Yes| process[Process order]
  validate -->|No| reject[Return validation errors]

The ID validate is used by edges; the label Input valid? can change without rewriting every connection. Stable IDs also make future styling and diff review easier.

Label decision branches

A diamond without edge labels forces the reader to guess which branch means yes or no. Attach short labels to outgoing edges with -->|Label|. Keep labels consistent across the diagram. Mixing true/false, yes/no, and success/failure for equivalent decisions creates unnecessary cognitive work.

Use subgraphs for boundaries

Subgraphs can show ownership or runtime boundaries:

flowchart LR
  subgraph Browser
    edit[Edit source] --> render[Render diagram]
  end
  subgraph LocalStorage
    draft[(Draft)]
  end
  edit --> draft

Do not wrap every group of two nodes in a subgraph. Boundaries are useful when they convey responsibility, trust, deployment, or lifecycle.

Avoid common parser surprises

Mermaid syntax evolves, but several errors are easy to isolate. Start from a minimal diagram and add one statement at a time. Quote labels containing punctuation when the parser interprets them as syntax. In flowcharts, the lowercase word end has a special role, so capitalize it or use a different node label. Also watch for an o or x directly after certain edge forms because those characters can select special edge endings.

Design for change

Large flowcharts become unreadable before they become technically invalid. Split a system overview from detailed process diagrams, keep edge crossings low, and use consistent levels of abstraction. A node named “System” next to nodes named after individual functions is a sign that the model mixes levels.

Test and export the source with the local Mermaid editor. The editor uses the Mermaid version bundled with the site, so a successful render verifies that exact runtime rather than every possible integration.