PlantUML vs Mermaid vs Graphviz DOT vs D2 — a complete DSL comparison

There are now more “text-first diagram tools” than 5 years ago — PlantUML / Mermaid / Graphviz DOT / D2. Which to pick? This post compares them against real scenarios.

One-line summary

PlantUML

Strengths

• Full UML family: sequence, state, class, activity, usecase, component, deployment, object — almost every UML diagram has dedicated syntax
• Functional style: !define / !function / !include / !pragma, programmable
• Theme ecosystem: !theme plus 20+ ready-made themes (cyborg / sketchy / crt-green, etc)
• Multi-runtime: Java CLI / docker server / WASM / online service

Pain points

• JVM dependency: CLI render requires Java; server docker image is 200MB+
• Slows at scale: 100+ nodes + Graphviz dot stutter (→ use ELK)
• Styling limits: limited built-in skins; custom CSS not possible
• Learning curve: !pragma / !define / <<stereotype>> are opaque to newcomers

Mermaid

Strengths

• Browser-native: pure JS; GitHub / GitLab / Notion / Obsidian all support it inline
• Zero install: drop a mermaid markdown block and it renders
• Common diagrams: flow / sequence / class / gantt / pie / state / ER all there
• Lowest learning curve: 5 minutes to first diagram

Pain points

• Limited styling: skin / theme are independent CSS-like key/values; precise control over node colour, font, spacing is awkward
• Slow at scale too: Canvas rendering, sluggish past ~50 nodes
• UML coverage thin: class diagram supports fields + methods only; sequence and state machine are passable
• No server: only browser, or the official CLI (less functional than the browser)
• PDF fidelity is poor (HTML → print → meh)

Graphviz DOT

Strengths

• Grandfather of graph tools: born 1991, the source of graph layout algorithms (dot / neato / fdp / sfdp / circo)
• Most algorithms: 5 layouts, each suited to a different shape
• Pure text: zero dependencies; one of the easiest visualisations for LLMs to generate correctly
• Composable with shell tools: csv2gprof | dot -Tsvg

Pain points

• Not UML: only draws graphs (nodes + edges); sequence / state machines must be hand-built
• Old syntax: digraph G { a -> b } is hard to debug in large graphs
• Styling is fiddly: every colour, shape, edge style needs an attr
• CJK fonts: need explicit fontname=…; slow overall without tuning

D2

Strengths

• Modern DSL: Go / TypeScript influence; consistent syntax, IDE-friendly autocomplete
• Layout algorithms: ELK / dagre / d2’s own (3 options)
• Styling as core: style.fill: ... / shape: ..., Figma-grade control
• Terraform / Postgres integration: from d2 -h read external data sources directly (e.g. arch.png auto-rendered from a terraform state)
• Browser WASM-friendly: layout can run in browser via dagre-wasm

Pain points

• Ecosystem is young: only v0.6+ in 2024; few enterprise adoption stories
• UML coverage thin: only class-diagram; sequence / state / deployment are missing
• Community docs are immature: bug-reporting leads to GitHub issues
• JS render is heavy: browser D2 is 1MB+; bad on mobile
• Chinese docs are scarce: only “intro” level exists in Chinese

Decision matrix: which when

Interop

PlantUML ↔ Mermaid

No official tool, just community packages:

• plantuml2mermaid / mermaid2plantuml — npm packages, only simple diagrams
• Manual translation: Mermaid sequence-diagram code is short, edit by hand

1
2
3

sequenceDiagram
  Alice->>Bob: Hello
  Bob-->>Alice: Hi back

1
2
3
4

@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi back
@enduml

PlantUML ↔ Graphviz DOT

Open-source plantuml2dot by Yegor Bugayenko.

PlantUML ↔ D2

D2 official supports d2 --plantuml=... flag, but only one direction. PlantUML → D2 has no complete converter.

Graphviz DOT ↔ Mermaid

viz.js / graphviz-cli chain — only handles simple graphs.

Benchmark: a 30-node microservice diagram

Conclusions:

• Mermaid is heaviest on cold start (100KB+ JS).
• Graphviz CLI is fastest (native C) but ugly output.
• PlantUML + ELK has the cleanest visual hierarchy.
• D2 is slightly slower but produces the most modern output.

My selection heuristics

“I” pick:

• Code-repo diagrams → PlantUML (stable API, full UML, JVM-friendly)
• GitHub README → Mermaid (zero config)
• Architecture whiteboarding → Graphviz dot (sketch on paper, write straight to dot, see diagram)
• Modern product docs → D2 (young ecosystem, but strong styling)
• Enterprise wiki (Feishu / Confluence) → Mermaid, with a path to PlantUML upgrade

Recap

There is no “best diagram DSL”. Only “DSL suited to the scenario”.

• PlantUML: engineering / UML / JVM integration → main weapon
• Mermaid: blogs / docs / lightweight diagrams → main weapon
• Graphviz: academic / automation / graph algorithms → auxiliary
• D2: modern styling / Terraform integration → fallback

Next

• PlantUML vs Mermaid vs Draw.io: which to pick for what
• Embedding PlantUML in Hexo (server-side / client-side) (actual slug: plantuml-render-from-hexo)