D2: A Modern Diagram-as-Code Language

March 27, 2026 · 7 min read

D2 is a declarative diagram language that compiles text into diagrams — like Mermaid, but with nested containers, pluggable layout engines, and built-in theming. It's gaining traction as a serious alternative for teams that outgrow Mermaid's limitations.

Key Takeaway: D2 offers more powerful layout and styling than Mermaid — nested containers, multiple layout engines (dagre, ELK, TALA), and themes. However, Mermaid has broader platform support (GitHub, Obsidian, Notion). Choose D2 for complex architecture diagrams; choose Mermaid for lightweight, platform-native rendering.

What Is D2?

D2 (Declarative Diagramming) is an open-source diagramming language created by Terrastruct. Like Mermaid, you write text and get a diagram. Unlike Mermaid, D2 was designed from the ground up for complex software architecture diagrams — with features like nested containers, multiple layout engines, and a theme system.

D2 compiles to SVG and PNG, and the CLI runs locally — no browser required. This makes it particularly well-suited for CI/CD integration, where diagrams can be auto-generated from text files on every commit.

D2 Syntax at a Glance

D2's syntax is minimal and readable. Here's a basic architecture diagram:

server: Backend Server {
  api: REST API
  db: PostgreSQL

  api -> db: queries
}

client: React App
client -> server.api: HTTP requests

cdn: CDN {
  style.fill: "#e8f4f8"
}
cdn -> client: static assets

The key difference from Mermaid is the nesting. In D2, you can nest elements inside containers using curly braces, creating natural grouping for microservices, modules, or infrastructure layers. In Mermaid, you'd need subgraphs with more verbose syntax.

Where D2 Excels

Nested containers — Group services, modules, or infrastructure layers naturally. Containers can be nested multiple levels deep, which is essential for cloud architecture diagrams.
Multiple layout engines — Switch between dagre (fast, good for simple graphs), ELK (better for large diagrams), and TALA (premium, best for complex architectures) without changing your diagram code.
Built-in themes — Apply consistent visual styles across diagrams without manual color picking. Themes include Terminal, Origami, and Grape, among others.
Imports and composition — Split large diagrams across multiple files and import them. This enables reusable diagram components — define your database schema once and import it across architecture views.
Animations — D2 supports animated connections (e.g., data flow arrows that pulse), useful for presentations and documentation.

Where Mermaid Still Wins

Platform support — Mermaid renders natively on GitHub, GitLab, Obsidian, Notion, and dozens of other platforms. D2 requires a build step or dedicated renderer.
Diagram variety— Mermaid supports Gantt charts, git graphs, pie charts, mindmaps, and other specialized diagram types that D2 doesn't cover.
Community size — Mermaid has a much larger ecosystem of plugins, integrations, and community resources. Finding help is easier.
Zero setup — Mermaid works in a fenced code block. D2 requires installing a CLI or using a web playground.

When to Use D2

D2 shines in specific scenarios:

Complex microservice architectures with nested service groups
Infrastructure diagrams (AWS/GCP/Azure) with clear layer boundaries
CI/CD-generated diagrams where you want consistent layout across builds
Teams that need reusable diagram components across documentation

For simple flowcharts, sequence diagrams, or diagrams that need to render inline on GitHub/Obsidian, Mermaid remains the pragmatic choice.

Converting D2 Output

D2 compiles to SVG, which can then be converted to other diagram formats. If your team needs the diagram in Draw.io for Confluence editing or in Excalidraw for further refinement, you can export the SVG and convert it using Orriguii Diagram Converter. This keeps D2 as your source of truth while distributing in any format.

Convert Diagram Files