D2 Guide

D2 is a declarative diagram language with a compact, readable syntax. Nodes, connections, and nested containers are all first-class.

Syntax, keys, comments, and direction

D2 uses indentation-based maps. Shape keys identify objects, labels can differ, and # starts a comment.

# Direction applies to this scope
direction: right

api: Public API
api.label: API gateway
client -> api

Keys are case-insensitive and connections target keys, not labels.
Use semicolons to declare several simple shapes on a line; quote labels when they collide with D2 syntax.
Set direction to up, down, left, or right at board or container scope.
Use underscores to reference a parent scope, dotted paths for children, and variables/imports to share configuration.

Nodes and connections

Declare a node with a label, then connect it with an arrow.

client: Client
api: API
db: Database

client -> api: request
api -> db: query
db -> api: result

name: Label creates a named shape.
a -> b makes a directed connection.
Put a label after the colon on a connection.

Containers and hierarchy

Nest services inside a boundary to show ownership, deployment, or a subsystem.

cloud: Cloud {
  api: API
  worker: Worker
  api -> worker
}
user: User
user -> cloud.api: HTTPS

A braced block creates a container.
Reference nested nodes with dot notation.
Use containers for real boundaries, not merely visual grouping.

Shapes and icons

Shapes communicate role before a reader has to parse the label.

decision: Ready? {
  shape: diamond
}
queue: Jobs {
  shape: queue
}
database: Records {
  shape: cylinder
}
service: API {
  icon: https://icons.terrastruct.com/essentials/Server.svg
}

Useful shapes include rectangle, square, circle, oval, diamond, hexagon, cloud, cylinder, queue, document, person, callout, and stored_data.
Use width, height, near, tooltip, link, and icon for shape-level presentation and interaction.
The default rectangle is often the clearest choice.

Style and layout

Use a small visual vocabulary for status and emphasis.

vars: {
  d2-config: {
    layout-engine: elk
  }
}
api: API {
  style: {
    fill: "#eeedff"
    stroke: "#635bff"
    font-color: "#35306f"
  }
}

Style keys include opacity, stroke, fill, fill-pattern, stroke-width, stroke-dash, border-radius, shadow, 3D, multiple, double-border, font, font-size, font-color, animated, bold, italic, underline, and text-transform.
Set layout-engine to dagre, elk, or tala according to the diagram.
Prefer one emphasis color over many unrelated colors.

Text, links, icons, and reusable classes

D2 supports Markdown and LaTex text blocks, interactive links, icons, and reusable properties without duplicating styles.

classes: {
  service: {
    shape: rectangle
    style: { fill: "#eeedff"; stroke: "#635bff" }
  }
}
api: |md
  ## Public API
  Validates requests
|
api.class: service
api.link: https://example.com
api.icon: https://icons.terrastruct.com/essentials/Server.svg

Use |md ... | for Markdown and |latex ... | for equations.
Set icon and link on shapes when output will be interactive.
Classes can supply labels, dimensions, shapes, and styles to multiple shapes or connections.

Specialized diagrams and advanced organization

D2 has purpose-built syntax for interactions, data models, UML, grids, and large multi-view diagrams.

user: User { shape: person }
orders: Orders { shape: sql_table
  id: int { constraint: primary_key }
  user_id: int { constraint: foreign_key }
}

shape: sequence_diagram
alice -> api: request
api -> alice: response

Built-in shapes include cloud, document, cylinder, queue, callout, stored_data, sql_table, and class.
Use shape: sequence_diagram for actors, ordered messages, groups, spans, and self-messages.
D2 also supports UML classes, grids, sketches, themes, animations, variables, imports, and layers/scenarios/steps boards.

✦

Keep it useful

Three working rules

Let the source mirror your architecture hierarchy.
Name nodes with stable IDs and keep the reader-facing label separate.
D2 supports several renderers; verify your target renderer before relying on a niche feature.

↗

Official sources