D2 — Modern Diagram Scripting Language

Introduction

D2 is a modern diagram scripting language developed by Terrastruct that compiles text to diagrams. It provides a readable, declarative syntax for creating architecture diagrams, flowcharts, sequence diagrams, and more, with automatic layout powered by multiple engines.

What D2 Does

• Compiles human-readable text definitions into SVG, PNG, and PDF diagram outputs
• Supports sequence diagrams, flowcharts, entity-relationship diagrams, and class diagrams
• Provides multiple layout engines including dagre, ELK, and TALA for automatic arrangement
• Enables theming, styling, and interactive tooltips on generated diagrams
• Offers a watch mode that live-reloads diagrams in the browser as you edit

Architecture Overview

D2 is written in Go with a pipeline architecture: the parser converts D2 text into an abstract syntax graph, the compiler resolves references and connections, a layout engine positions nodes, and the renderer emits the final SVG or image. Layout engines are pluggable, allowing users to choose between the open-source dagre/ELK backends or the proprietary TALA engine for advanced layouts.

Self-Hosting & Configuration

• Install the d2 binary on Linux, macOS, or Windows via the official install script or package managers
• Run d2 --watch input.d2 output.svg for a live-reloading development workflow
• Configure default theme, layout engine, and output format via CLI flags or a d2 config file
• Integrate into CI pipelines to auto-generate documentation diagrams on every commit
• Use the D2 Playground (TALA-powered) for browser-based editing without local installation

Key Features

• Readable syntax with minimal boilerplate compared to DOT or Mermaid
• First-class support for sequence diagrams with actors, spans, and notes
• Built-in themes (including dark mode) and extensive styling options via D2 style blocks
• Composable imports allow splitting large diagrams across multiple files
• CLI-first design with watch mode, making it easy to embed in dev workflows

Comparison with Similar Tools

• Mermaid — browser-native and widely embedded in Markdown renderers, but less expressive layout control
• PlantUML — mature UML-centric tool with Java dependency; D2 is a single Go binary
• Graphviz (DOT) — powerful graph layout but archaic syntax; D2 offers a modern developer experience
• Excalidraw — hand-drawn style visual editor; D2 is text-first and version-control friendly
• Structurizr — focuses on C4 architecture models; D2 is general-purpose diagramming

FAQ

Q: Is D2 free and open source? A: Yes, D2 is open source under the MPL-2.0 license. The TALA layout engine is proprietary but optional.

Q: Can I use D2 in my documentation pipeline? A: Absolutely. D2 integrates with CI/CD systems and supports output to SVG, PNG, and PDF formats.

Q: Does D2 support dark mode? A: Yes, D2 ships with multiple built-in themes including several dark mode variants.

Q: How does D2 compare to Mermaid for Markdown docs? A: D2 offers more layout control and diagram types, while Mermaid has broader native Markdown rendering support.

Sources

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