d2

Overview ¶

Package d2 generates D2 (https://d2lang.com) source text for a built plan.

It mirrors the mermaid package shape (Source / SourceWithOptions / NewRenderer) and consumes the backend-neutral graph IR via visualize.BuildGraph. The output is unlaid-out D2 source; render it with the d2 CLI, for example `d2 out.d2 out.svg`.

D2 dialect decisions ¶

• Direction: `direction: down` is emitted explicitly. Edges point from parent to child, so with the top-down flow the root sits at the top and children below it.
• Nodes are declared with flat statements (`nodeN.shape: rectangle`, `nodeN.label: |md ... |`, `nodeN.tooltip: |yaml ... |`) rather than an inline `{ ... }` map, because D2 block strings span multiple lines and do not compose cleanly inside a single-line inline map.
• Labels are markdown blocks. The label Title is a bold (`**...**`) line, Body lines are plain, Body key/value pairs use the `key: value` dialect (chosen over the graphviz `key=value` form for readability), and Stats and Summary lines are italic (`_..._`). The body lines are joined into a single markdown paragraph with CommonMark hard line breaks (a trailing backslash), giving tight single-line spacing that matches the graphviz/mermaid backends; the bold title is kept as its own paragraph for a small visual separation from the body. (An earlier version emitted every line as its own blank-line-separated paragraph, which rendered with a paragraph gap between every line.)
• Emphasis markers hug their content: any leading whitespace on a Stats or Summary line is moved OUTSIDE the `_..._` markers and re-encoded as ` ` entities (which d2's markdown renderer honors) so the visual indent survives, and trailing whitespace is trimmed from inside the markers. CommonMark requires the opening `_` to be immediately followed by, and the closing `_` immediately preceded by, a non-whitespace character; a space-indented summary child line such as `_ num_executions: 1_` would otherwise fail to parse as emphasis and render with literal underscores. See emphasizeD2Line.
• Markdown metacharacters in label content are backslash-escaped conservatively (see escapeD2Markdown). The pipe character is not escaped; it is handled at the D2 block-string layer by widening the fence.
• Tooltips carry the canonical YAML in a `|yaml ... |` block string. D2 renders tooltips as plain-text HTML title attributes (markdown and syntax highlighting are not applied), so the YAML is carried verbatim; only the fence width matters for escaping.
• Block-string fences use the documented pipe-widening rule: a run of N pipes where N is one greater than the longest run of consecutive pipes in the content, so the content can never contain the closing delimiter.
• Edges carry the Spanner link type as an unquoted label (a simple closed vocabulary such as "Map" or "Split Range"). Dashed and Dotted edges get `{style.stroke-dash: 3}`; D2 has no separate dotted stroke style, so both map to the same dash pattern (mirroring the mermaid backend, which also collapses them).
• The optional query node is a distinct `query` shape with rounded corners (`style.border-radius: 8`) whose label is the query text in bold followed by italic stat lines. It is linked with `root -> query`, placing it below the plan under the top-down flow.