Reading A Lesson

D2 walkthroughs

One D2 source, many boards, and a reader who clicks their way down through them.

Suggest an edit

D2 walkthroughs

The snippets lesson draws one picture per fence. Some diagrams are not one picture, though — a C4 stack, a zoom-in, a system explained one level at a time. D2 calls those layers, and a source that uses them compiles to a tree of boards rather than a single figure.

D2's own way to show all of them is --animate-interval, which cycles through the boards on a timer nobody can stop. A walkthrough hands the reader the wheel instead: click a node to drill into it, step back out, jump straight to any level.

Try it. Click URL Shortener below.

Link creator[Person]Link visitor[Person]URL Shortener[Software System]DNS provider Creates short linksResolves sho.rtGET /abc123

Four boards, one source. Enlarge works too, and the walkthrough stays navigable inside it — clicking a node in the enlarged view drills down exactly the same way.

Writing one

Add the boards marker to a d2 fence — so the opening line of the fence above reads d2 boards name="c4-url-shortener" root="System Context". Without the marker, a layers: diagram renders its root board only and the drill-down links do nothing.

Marker What it does
boards Required. Opts the fence into the walkthrough viewer.
name="…" Names the folder the drawn boards are committed to. Optional, but it makes the diff readable.
root="…" The first board's title. Layer titles come from their keys; the root has no key.

Each nested board is a key under layers:, and a node becomes clickable by carrying a link: to another board.

The one thing that trips everyone

link: is resolved against the board it is written in.

At the top level, link: layers.container means "the container layer" and works. One level down — inside layers.container — that exact text means container's own component layer, which doesn't exist. D2 then drops the link silently: no error, no warning, and d2 validate still reports success. The node just quietly stops being clickable.

Use _ to step up to the parent board:

layers: {
  container: {
    api: "Public API" {
      link: layers.component      # ✗ silently dropped
      link: _.layers.component    # ✓ `_` is the parent board
    }
  }
}

Because the compiler keeps no record of a link it dropped, Synapse checks the source when it draws your diagrams, and tells you exactly where:

03-d2-walkthroughs.md:71: `link: layers.component` in board root.layers.container
  names no board — did you mean `link: _.layers.component`?

Links to real URLs (https://…) are left alone and open in a new tab.
Click a node Drills into the board it links to
‹ › Back and forward through the boards you have visited
⌂ Straight back to the first board
☰ Jump to any board by name
← → Same as ‹ ›, from the keyboard
Breadcrumb Shows where you are; every step in it is clickable

The board you are looking at is written into the page address, so sending someone the link sends them to the board you meant. Your browser's own Back button still leaves the lesson in one press — the diagram never takes it over.

Drawing your own

The /d2 editor is the fastest way in: write on the left, drive the result on the right, then copy the finished fence straight into a lesson.

Boards are drawn once, when the content is published, and the reader's page simply looks them up — so a walkthrough costs a reader no more than an ordinary diagram, however many boards it holds.

Mark as read