D2 Diagram Language: The Modern Alternative to Mermaid and PlantUML

D2 (Declarative Diagramming) is an open-source diagram scripting language designed specifically for software architecture diagrams. Released by Terrastruct in 2022, it addresses the two biggest frustrations with existing diagram-as-code tools: poor automatic layout for complex graphs and verbose syntax for architecture-specific constructs. If you've ever fought Mermaid's auto-layout or PlantUML's syntax for a cloud architecture diagram, D2 is worth a look.

What makes D2 different

D2 makes three bets that distinguish it from Mermaid and PlantUML:

• TALA layout engine: D2 ships with TALA (Tree Automatic Layout Algorithm), a proprietary but free-to-use layout engine that produces significantly better automatic layouts for architecture diagrams than Mermaid's Dagre or PlantUML's default. Nodes don't overlap, edges route around obstacles, and hierarchies are drawn cleanly.
• Container-first syntax: D2's syntax treats containers (groups of components) as first-class citizens. Nesting services inside networks or availability zones is natural, not an afterthought.
• Architecture-native features: D2 has built-in support for shapes like SQL tables (with column definitions), classes, and sequences — without needing workarounds.

D2 syntax basics

D2 uses a clean, readable syntax. Here's a simple microservices architecture:

The result is a clean diagram with properly routed edges and labeled connections — no manual positioning needed.

D2 containers and nesting

D2's container syntax makes it easy to show cloud boundaries, VPCs, and availability zones:

D2 vs Mermaid vs PlantUML: feature comparison

When to choose D2

D2 is the best diagram-as-code choice when:

• You're diagramming complex architectures where layout quality matters — D2's TALA engine handles 20+ node diagrams better than Mermaid
• You need nested containers for cloud boundaries, VPCs, or availability zones — D2's container syntax is significantly cleaner
• You want readable, maintainable diagram-as-code in a monorepo — D2 files are concise and easy to diff
• GitHub native rendering isn't a hard requirement for your workflow

When to choose Mermaid instead

• You need native GitHub, GitLab, or Notion rendering — Mermaid is natively supported, D2 requires a plugin
• You need flowcharts, Gantt charts, pie charts, or other non-architecture diagram types — Mermaid's library is broader
• Your team is already familiar with Mermaid and the switching cost isn't justified

The fastest path: AI-generated diagrams

If your goal is getting a professional architecture diagram quickly — not learning a new scripting syntax — AI-generated diagrams are the fastest path. With ArchitectureDiagram.ai, you describe your architecture in plain English and get a diagram instantly, without writing D2, Mermaid, or PlantUML syntax. You can then export to Mermaid format if you need to embed it in GitHub docs.

Use D2 (or Mermaid, or PlantUML) when you need diagrams that live in code and can be version-controlled with the system they describe. Use AI-generated diagrams when you need to communicate quickly to a mixed audience or don't want the overhead of maintaining a text-based diagram format.

Related guides: Mermaid.js vs traditional diagramming, diagram as code explained, and ArchitectureDiagram.ai vs PlantUML.