D2 vs Mermaid vs PlantUML

There is no universal winner. Mermaid optimizes for fast documentation, D2 for expressive architecture diagrams, and PlantUML for formal UML and established engineering conventions.

At a glance

Use the tool whose strongest convention matches the diagram you need to explain.

Mermaid — best default for Markdown-first documentation and quick team diagrams.
D2 — best for clear systems maps, nested architecture, and visual control with concise source.
PlantUML — best for UML, sequence-heavy design, and teams that already rely on its broad notation set.

Syntax and learning curve

All three are approachable, but their source reads differently.

text

Mermaid:   flowchart LR
D2:        browser -> api
PlantUML:  Browser -> API: request

Mermaid has recognizable diagram-type keywords and a quick path from Markdown to a diagram.
D2 reads close to an architecture inventory: nodes, connections, then nested boundaries.
PlantUML rewards learning its vocabulary; that investment pays off in formal diagram types.

Rendering and collaboration

Rendering context often decides more than raw syntax preference.

Choose Mermaid when your docs platform already renders it or your team writes in Markdown.
Choose D2 when you control a build step and want a polished architecture renderer.
Choose PlantUML when your team has a renderer, shared skins, or existing UML workflows in place.

A practical decision rule

Start with the simplest language that preserves the meaning the reader needs.

text

Docs and quick flows        → Mermaid
Architecture and boundaries   → D2
UML and formal interactions   → PlantUML
Generated graph relationships → Graphviz

Prefer consistency inside a repository over changing language for every diagram.
Create a small style guide: direction, labels, color semantics, and where source lives.
If a diagram has become difficult to read, split the question into two diagrams before adding syntax.

✦

Keep it useful

Three working rules

Mermaid is the lowest-friction default for most product documentation.
D2 is the nicest fit when the diagram itself is a crafted architecture artifact.
PlantUML is often the best choice when standard UML symbols are part of the shared language.

↗

Official sources