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:

   me -> d2: "trying this out"
   d2 -> diagram: "generates automatically"
   

3. Render it:

   d2 hello.d2 hello.svg
   

4. Open the output – You'll get a clean SVG in seconds.

There's also a playground if you want to try it in your browser first.

Final Thoughts

D2 nails the developer experience. It's fast, predictable, and doesn't get in your way. For quick architecture sketches, system diagrams, or even sequence diagrams (it supports those too), it's hard to beat.

Will it replace Lucidchart for complex, collaborative whiteboarding? No. But for docs that live next to your code and need to stay correct, D2 is a solid choice. I've already started using it for my side projects, and I'm considering pushing it at work.

Give it a shot. Worst case, you delete the binary after 30 seconds. Best case, you stop opening Excalidraw for every "quick diagram."

Found this interesting? Follow us at @githubprojects for more developer tools and open source finds.