D2 Diagrams

Use D2 when a diagram needs nested containers and boundaries, a database schema with primary and foreign keys, or a layout you can tune by swapping engines. Mermaid still fits quick flowcharts. Switch to D2 when the structure gets architectural. You write D2 the same way as Mermaid, in a fenced code block in your Markdown.

Basic Usage

Use a fenced code block with the d2 language identifier:

```d2
a -> b -> c
```

Diagram Types

Architecture

Architecture diagrams map how services connect. Use labeled shapes to show the request path through your system.

```d2
Client: Web Client
API: API Server
Database: { shape: cylinder }

Client -> API: request
API -> Database: query
```

Containers

Containers group related nodes. Nest shapes inside { } to model boundaries like a cloud account or a deployment. Then draw connections that cross those boundaries.

```d2
cloud: Cloud {
  api: API
  worker: Worker
}

queue: Message Queue

cloud.api -> queue: publish
queue -> cloud.worker: consume
```

Sequence Diagrams

Sequence diagrams show how components talk over time. Set shape: sequence_diagram on a container. List messages in order to document an API or authentication flow.

```d2
flow: {
  shape: sequence_diagram

  Client -> Server: request
  Server -> Database: query
  Database -> Server: results
  Server -> Client: response
}
```

Class Diagrams

Class diagrams document the structure of object-oriented systems. Set shape: class on a node and list its fields and methods. Prefix members with + for public, - for private, or # for protected. Connect classes to show their relationships.

```d2
User: {
  shape: class
  +name: string
  +email: string
  +login(): void
  +logout(): void
}

Order: {
  shape: class
  +id: int
  +created: date
  +addItem(): void
  +checkout(): void
}

Item: {
  shape: class
  +name: string
  +price: float
}

User -> Order: places
Order -> Item: contains
```

State Diagrams

State diagrams model the lifecycle of an object or process. D2 doesn't have a dedicated state-diagram shape. Model states as ovals or circles, then draw labeled transitions between them.

```d2
Draft: { shape: oval }
Review: { shape: oval }
Published: { shape: oval }
Archived: { shape: oval }

Draft -> Review: submit
Review -> Published: approve
Review -> Draft: request changes
Published -> Archived: archive
```

SQL Tables

SQL table shapes document a database schema with columns and types. Mark a column with { constraint: primary_key } or { constraint: foreign_key } to render PK and FK badges. Connect a foreign key to its referenced table to show the relationship.

```d2
users: {
  shape: sql_table
  id: int { constraint: primary_key }
  email: varchar
}

orders: {
  shape: sql_table
  id: int { constraint: primary_key }
  user_id: int { constraint: foreign_key }
  total: decimal
}

orders.user_id -> users.id
```

Shapes

Set a shape on any node to change how it renders:

Connections

Connections define direction and relationships between nodes:

Choosing a Layout Engine

D2 ships with several layout engines. The default is dagre. Switch to ELK for denser graphs with D2's native config block in the diagram source. No component prop sets the engine in this release.

```d2
vars: {
  d2-config: {
    layout-engine: elk
  }
}

ingress -> service -> database
```

Wide diagrams scroll horizontally inside their container. They never overflow the page.

Styling Tips

• Keep each diagram small: split a large system into focused views.
• Label each connection with its relationship.
• Group related nodes into containers instead of one flat graph.
• Switch to the ELK layout engine for dense graphs with many connections.

D2 vs Mermaid

D2 and Mermaid render at build time. Pick by fit:

• Pick D2 for architecture and infrastructure diagrams, SQL and ER models, sketch-style visuals, and when you want a choice of layout engines.
• Pick Mermaid for flowcharts, Gantt charts, and Git graphs. Mermaid's sequence syntax has more features than D2's. D2 sequence diagrams keep the rest of your diagram in one language. Mermaid is widely adopted.

See the Mermaid Diagrams page for Mermaid syntax and examples.

Learn More

See the official D2 documentation for the full syntax, including styling, classes, and animation.

What's Next?