D2 Diagrams

Reach for 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. It sits alongside the Mermaid support already in Jamdesk: keep using Mermaid for quick flowcharts, and move to D2 when the structure gets architectural. Both share the same authoring spot — a fenced code block in your Markdown — so picking one is a question of fit, not workflow.

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 and 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, and 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, then 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 multiple layout engines. The default is dagre. To switch to ELK for denser graphs, set it in the diagram source using D2's native config block. There is no component prop for this in this release; the engine is selected in the diagram itself.

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

ingress -> service -> database
```

Wide diagrams scroll horizontally inside their container, so a dense graph stays readable without overflowing the page.

Styling Tips

For effective diagrams:

• Keep each diagram small: split a large system into focused views.
• Label connections so the relationship is clear at a glance.
• 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

Both languages render at build time, so the choice comes down to 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. Both render sequence diagrams; Mermaid's sequence syntax is more feature-rich, while D2's keeps the rest of your diagram in one language. Mermaid is widely adopted and has a broad ecosystem.

See the Mermaid Diagrams page for Mermaid syntax and examples.

Learn More

For the full D2 syntax reference, including styling, classes, and animation, see the official D2 documentation.

What's Next?