D2 — Text-to-Diagram Scripting Language for Developers

Introduction

D2 is a modern, declarative diagramming language developed by Terrastruct. You write text descriptions and D2 compiles them into SVG, PNG, or PDF output. It focuses on readability, making diagrams easy to version-control alongside code.

What D2 Does

• Compiles .d2 text files into SVG, PNG, and PDF diagrams with automatic layout
• Supports multiple layout engines including dagre, ELK, and TALA
• Provides containers, connections, shapes, icons, and markdown labels
• Includes watch mode that live-reloads rendered output as you edit
• Handles sequence diagrams, class diagrams, and ER diagrams natively

Architecture Overview

D2 is written in Go and operates as a CLI compiler. Source files are parsed into an AST, processed through a pluggable layout engine, then rendered to the chosen output format. Open-source layout engines dagre and ELK are bundled; the TALA engine is an optional proprietary add-on.

Self-Hosting & Configuration

• Install from source with go install oss.terrastruct.com/d2 or use prebuilt binaries
• Configure layout engine, theme, and output format via CLI flags
• Built-in themes are selectable by name; dark-mode variants included
• Embed D2 in CI pipelines to auto-generate diagrams on each commit
• Use the VS Code extension for syntax highlighting and inline preview

Key Features

• Declarative syntax: readable, indentation-based text format
• Multiple output formats: SVG, PNG, and PDF from the same source
• Pluggable layouts: choose dagre, ELK, or TALA per diagram
• Sequence diagrams: first-class lifelines and message arrows
• Markdown labels: inline markdown for rich text inside shapes

Comparison with Similar Tools

• Mermaid: browser-native, widely embedded in doc platforms; D2 offers more layout control
• PlantUML: mature UML focus; D2 has cleaner syntax and faster rendering
• Graphviz: classic graph layout tool; D2 provides modern syntax and better defaults
• Excalidraw: hand-drawn canvas editor; D2 is text-first and version-control friendly

FAQ

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

Q: Can I use D2 in CI/CD pipelines? A: Yes. D2 is a standalone CLI binary that integrates into any CI pipeline.

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

Q: How does D2 compare to Mermaid? A: Mermaid renders in-browser and is natively supported by GitHub. D2 produces higher-quality output with more layout options but requires a build step.

Sources

• Repository: https://github.com/terrastruct/d2
• Documentation: https://d2lang.com/tour/intro