Diagrams as Code: Turn Text into Architecture Diagrams

You're deep in a design doc, trying to explain how your microservices talk to each other. You could draw a diagram by hand, but that's slow, fragile, and impossible to version control. Or you could write a few lines of text and get a clean, scalable diagram that lives in your repo.

Enter D2: a DSL that turns plain text into architecture diagrams. No drag and drop, no pixel pushing. Just write, render, repeat.

What It Does

D2 is a declarative diagramming language. You describe your system's components and connections in a simple text file, then run the CLI tool to generate a PNG, SVG, or PDF diagram. The syntax looks like this:

cloud_front -> api_gateway -> lambda_functions -> dynamodb

That's it. No XML, no JSON blobs, no YAML indentation headaches. Just arrows and labels. D2 handles layout, routing, and styling automatically.

Why It's Cool

Version control friendly. Your diagram is a text file. You can diff it, review it, and merge it just like code. No "diagram_v3_final_actuallyfinal.png" ever again.

Smart layout by default. D2's layout engine (it uses TALA under the hood) produces clean, readable diagrams without manual positioning. It avoids overlapping arrows and keeps things organized. You can still tweak positions if you want, but 95% of the time the default just works.

Composable and granular. Define a shape once, reuse it everywhere. Group components into containers. Add labels, notes, and even tooltips. You can build complex diagrams from small, manageable pieces.

No dependencies. The D2 binary is a single file. No Node.js, no Python, no Docker. Download, unzip, run. That's a breath of fresh air for a diagramming tool.

Great for CI/CD. Automate diagram generation as part of your build pipeline. Every commit can produce updated architecture docs. Your README stays accurate without manual effort.

How to Try It

The easiest way to see D2 in action is to install it and run a quick example.

1. Install – On macOS or Linux via Homebrew:

   brew install d2
   

   Or download the binary for your OS.

2. Write a diagram – Create a file called hello.d2: