Why D2’s 24k‑Star Open‑Source Diagram Language Beats PlantUML and Mermaid

D2: Declarative Diagram Language with Indentation‑Based Hierarchy

D2 lets you write plain text that directly maps to diagram hierarchy; indentation defines parent‑child relationships, eliminating the need for explicit node declarations required by Mermaid and PlantUML. x -> y -> z Installation is simple: a one‑line curl script or brew install d2 works on macOS without Java or environment variables.

Why Existing Tools Fall Short

PlantUML struggles with architecture diagrams, often producing misplaced nodes and requiring many skinparam, ortho, and linetype tweaks. Mermaid’s automatic layout collapses after about fifteen nodes and offers few layout controls. Graphviz’s DOT language is dated and produces overly technical visuals.

D2’s Advantages Over Legacy Tools

Indentation Determines Hierarchy

Example:

network: {
  cell tower: {
    satellites: {
      shape: stored_data
      style.multiple: true
    }
    transmitter
  }
}

Saving the file and running d2 --watch in.d2 out.svg triggers hot‑reload similar to front‑end development, instantly updating the diagram.

Three Built‑In Layout Engines

D2 includes Dagre (default, good for hierarchical graphs), ELK (handles complex connections), and TALA (Terrastruct’s custom engine for large architecture diagrams). Switching is done via a simple config block:

vars: {
  d2-config: {
    layout-engine: elk
  }
}

In practice, Dagre suffices for most cases, ELK excels with nested containers, and TALA offers the best results for very large diagrams, though it requires separate installation.

Professional Themes and Sketch Mode

D2 ships with multiple polished themes (light, dark, business) that can be selected with a single line like theme-id: 1. Unlike PlantUML’s verbose skinparam blocks, D2’s themes are designed by professional designers. A sketch mode provides hand‑drawn‑style diagrams, and dark‑mode support automatically adapts colors.

Precise Error Reporting

D2’s parser reports the exact line, problem, and suggested fix, e.g., “line 47: missing target node after x -> ”. PlantUML only returns a generic “Syntax Error?” and Mermaid provides a stack trace.

Rich Plugin Ecosystem

Official plugins exist for VSCode, Vim, Obsidian, Slack, and Discord; community contributions add support for Emacs, Confluence, Maven, and Pandoc. The VSCode plugin offers syntax highlighting, autocomplete, and live preview.

Major projects such as ElasticSearch, Sourcegraph, Temporal, Tauri, JetBrains IntelliJ, and LocalStack have adopted D2 for architecture diagrams.

Go Library for Programmatic Diagram Generation

Go developers can import D2 as a library:

import "oss.terrastruct.com/d2/d2compiler"
import "oss.terrastruct.com/d2/d2renderers/d2svg"

This enables CI pipelines to generate up‑to‑date diagrams from code or database schemas.

Animation Support

D2 uniquely supports animated SVGs by defining multiple steps, allowing a single file to illustrate architectural evolution—something Mermaid, PlantUML, and draw.io cannot do.

Current Shortcomings

GitHub does not natively render D2, its icon library is less comprehensive than draw.io, and the TALA layout engine has a paid Pro version.

These gaps mean users must generate SVGs in CI or use community GitHub Actions, and may need to source custom icons for cloud architecture diagrams.

Conclusion

D2 is a powerful, easy‑to‑learn diagram tool with a syntax reminiscent of YAML, offering professional themes, robust layout engines, precise error messages, and extensibility via plugins and a Go library. While it lacks native GitHub rendering and has a limited icon set, its advantages make it a compelling alternative to PlantUML and Mermaid for teams needing consistent, high‑quality documentation.