Why Developers Are Turning to D2: A Code‑Like, Engineerable Diagramming Tool

When documenting architecture, the author struggled with traditional drag‑and‑drop editors like draw.io, which produce misaligned lines and require complete redraws after requirement changes.

Discovering the open‑source project D2 (Declarative Diagramming) on GitHub, the author found a script‑based approach that converts text into diagrams, eliminating manual alignment and enabling engineering‑style management.

Core Concept

D2 is a Go‑implemented language that treats diagram definitions as code, allowing pure‑text descriptions, Git version control, collaborative review, automation, and AI‑driven generation.

Key Features

Production‑grade themes : Over 100 professionally designed themes switchable with the -t flag.

Sketch mode : The --sketch flag adds a hand‑drawn jitter for informal presentations.

Animated charts : Unique ability to animate node and edge appearance, useful for illustrating flows.

LaTeX support : Direct embedding of mathematical formulas, ideal for research notes and papers.

Multilingual text : Handles Chinese, English, French, emojis, etc., without rendering issues.

Code‑block highlighting : Embed syntax‑highlighted code snippets directly in architecture diagrams.

Additional capabilities include multiple layout engines (Dagre, ELK, TALA), live preview with watch, modular file imports, and dark‑mode adaptation.

Quick Installation and First Use

# macOS / Linux universal installer
curl -fsSL https://D2lang.com/install.sh | sh -s --

# Homebrew on macOS
brew install D2

# With Go toolchain
go install oss.terrastruct.com/D2@latest

Windows users can install via winget install terrastruct.D2. After installation, a minimal "Hello World" diagram can be created:

# Create a D2 file
 echo 'x -> y -> z' > hello.D2

# Watch mode for live preview
 D2 --watch hello.D2 out.svg

The browser opens automatically, and any file edit refreshes the diagram instantly.

For those who prefer not to install locally, an online Playground is available at https://play.D2lang.com, and plugins exist for VSCode, Vim, and Obsidian, covering most common editors.

Conclusion

Using D2 feels like the "programmer's proper way to draw"; it transforms one‑off diagramming into maintainable, version‑controlled assets, freeing developers from tedious alignment work and enabling integration with automated and AI‑driven workflows.