D2 — Declarative Diagram Scripting Language

Introduction

D2 is a modern diagram scripting language that compiles text into diagrams. It provides a human-readable syntax purpose-built for software architecture, flowcharts, sequence diagrams, and entity-relationship models, allowing developers to version-control their diagrams alongside code.

What D2 Does

• Compiles plain-text .d2 files into SVG, PNG, or PDF diagrams
• Supports multiple diagram types: flowcharts, sequence diagrams, entity-relationship, and class diagrams
• Offers automatic layout via pluggable engines (dagre, ELK, TALA)
• Provides a watch mode that live-reloads diagrams in the browser on file save
• Handles nested containers, connections, icons, and theming natively

Architecture Overview

D2 is written in Go and operates as a compiler pipeline. The parser reads .d2 source into an AST, the compiler resolves references and connections, and a layout engine positions nodes and edges. The renderer then outputs the final image. Layout engines are pluggable: the open-source dagre and ELK engines ship by default, while the commercial TALA engine offers more advanced routing.

Self-Hosting & Configuration

• Single binary install on Linux, macOS, and Windows with no runtime dependencies
• Also available via Homebrew, npm, and Docker
• Integrate into CI pipelines to auto-generate diagrams from source on every commit
• Theme customization through built-in themes or custom color overrides
• Use d2 fmt to auto-format .d2 files for consistent team style

Key Features

• Clean, readable syntax: x -> y defines a connection with minimal boilerplate
• Pluggable layout engines let you trade off speed for layout quality
• Watch mode with live browser reload for rapid diagram iteration
• Markdown and LaTeX support inside diagram labels
• Importable and composable: split large diagrams across multiple files with ...@file.d2

Comparison with Similar Tools

• Mermaid — embedded in Markdown renderers; D2 offers richer layout options and a standalone compiler
• PlantUML — Java-based with UML focus; D2 is a single Go binary with broader diagram types
• Graphviz (DOT) — venerable but minimal styling; D2 provides modern themes and nested containers
• Excalidraw — freehand drawing tool; D2 is text-to-diagram for version-controlled output

FAQ

Q: Can D2 diagrams be embedded in documentation sites? A: Yes. Generate SVGs at build time and embed them, or use community plugins for MkDocs, Docusaurus, and Hugo.

Q: How does D2 compare to Mermaid for Git-based workflows? A: Both are text-to-diagram. D2 supports more layout engines, nested containers, and standalone CLI use, while Mermaid has broader native Markdown renderer support.

Q: Is the TALA layout engine required? A: No. D2 ships with dagre and ELK (both open source). TALA is an optional commercial engine for advanced automatic layout.

Q: Does D2 support dark mode? A: Yes. D2 includes multiple built-in themes including dark variants, selectable via the --theme flag.

Sources

• https://github.com/terrastruct/d2
• https://d2lang.com/