D2 Text-to-Diagram DSL

D2's long-term goal is to reduce the effort required to create and maintain high-quality diagrams for software teams. The current development priorities are:

1. Expand Layout Coverage: Increasing the variety of diagram types that can be automatically laid out.
2. Minimize Aesthetic Effort: Making it easier to produce professional-looking diagrams through themes and granular customization.
3. Developer Tooling Integration: Improving support for existing workflows, editor extensions, and programmatic manipulation.

Certain shapes in D2 maintain a 1:1 aspect ratio, meaning their width and height are always equal. This includes:

• circle
• square

Behavioral rules for 1:1 shapes:

• Label scaling: If a long label makes the shape wider, D2 will automatically increase the height to maintain the ratio.
• Manual dimensions: If you manually set both width and height, D2 will set both dimensions to the larger of the two values to preserve the 1:1 ratio.

# Example of a 1:1 shape
MyCircle.shape: circle
MyCircle.width: 100
MyCircle.height: 50 # Will be rendered as 100x100

Use the vars keyword to define variables that can be reused throughout your diagram. To reference a variable, use the substitution syntax ${variable_name}.

vars:
  my_var: hello

shape: ${my_var}

When working inside a container, you may need to reference an element or property that exists outside of it (in the parent scope). Use the underscore (_) symbol to refer to the parent container.

parent_container: {
  child: {
    # Refers to parent_container
    _ -> some_external_node
  }
}

D2's autoformatter automatically corrects the indentation of block strings (strings starting with |).

If a block string's indentation is insufficient, the autoformatter identifies non-empty lines with insufficient indent and prepends them with the correct amount of indentation while respecting the existing common indent. This allows you to paste code into the first column after the block string marker without manually adjusting the indentation.

parent: {
example_code: |go
package fs

type FS interface {
  Open(name string) (File, error)
}
|
}

D2 Oracle (d2/d2oracle) is a Go package that provides an API for programmatically creating and manipulating D2 diagrams by operating on its Abstract Syntax Tree (AST).

Key Concept: Immutability

All functions in d2oracle are pure. They do not mutate the original graph; instead, they return a new modified graph. When chaining operations, you must always use the resulting graph from the previous call.

Multi-board Diagrams

For diagrams containing multiple boards, most functions accept a boardPath (a []string) to specify which board to modify. For single-board diagrams, pass nil.

// Example of the required chaining pattern due to immutability
g, _ = d2oracle.Create(g, nil, "a")
g, _ = d2oracle.Set(g, "a.style.fill", nil, "red")

D2 is a specialized tool for documenting software architecture. It is not a general-purpose visualization tool.

What D2 is for:

• Describing software systems via nodes and edges.
• Creating "whiteboard-fit" diagrams (simplified representations of systems).

What D2 is NOT for:

• General visualization (e.g., mind maps, Gantt charts, Sankey diagrams, or Venn diagrams).
• Large-scale graph theory visualization (e.g., diagrams with >1000 nodes where the goal is pattern recognition rather than understanding individual components).