Flowcharts in Markdown: Mermaid vs Graphviz vs D2

Three of the most popular diagram tools available in this editor — Mermaid, Graphviz, and D2 — can all produce flowcharts. But they have very different philosophies, layouts, and strengths. This guide compares them with equivalent examples.

The Same Flowchart in All Three Tools

Let’s draw a simple deployment pipeline in all three tools.

Mermaid

Mermaid

Mermaid syntax:

flowchart LR
    A[Code Push] --> B[CI Tests]
    B -->|Pass| C[Build Docker Image]
    B -->|Fail| F[Notify Developer]
    C --> D[Push to Registry]
    D --> E[Deploy to Production]

Graphviz (DOT)

Graphviz

D2

D2

Side-by-Side Comparison

When to Use Mermaid for Flowcharts

• You need a quick diagram and don’t want to configure much
• The flowchart is linear or tree-shaped (not a complex network)
• You are familiar with other Mermaid diagram types and want consistency
• The flowchart needs to be embedded in documentation quickly

Mermaid’s best feature for flowcharts: Natural reading syntax — A --> B is immediately obvious.

When to Use Graphviz for Flowcharts

• You need precise layout control with rank, weight, and ordering attributes
• The diagram has many nodes and automatic ranking handles complexity well
• You need complex node shapes (records, nested labels, ports)
• You are drawing dependency graphs, call graphs, or FSMs where Graphviz’s layout algorithms shine

Graphviz’s best feature: The DOT layout engine (dot, neato, fdp, circo) is the most sophisticated automatic layout engine available.

When to Use D2 for Flowcharts

• You want clean, modern visual output with minimal configuration
• The flowchart includes containers or grouped steps (D2’s container syntax is elegant)
• You are drawing software architecture that also includes database or service boxes
• You care about consistent visual style across a documentation suite

D2’s best feature: Container blocks make grouping related steps trivial:

D2

Recommendation