1# d2
2
3sublimated renders `.d2` files as diagrams. push via [git](../git/), view the rendered diagram on the web.
4
5- diagrams are rendered server-side on push — no client-side JavaScript needed
6- the rendered SVG is stored alongside the source, so viewing is instant
7- edit mode uses CodeMirror with D2 syntax highlighting
8- supported on both sublimated.com (file viewer) and run.sublimated.com (published sites)
9- inline comments and reactions work on the rendered diagram (SVG is inline DOM)
10- D2 node IDs are user-defined and stable — comment anchoring survives edits
11
12## demos
13
14one file per diagram type — push them to see them rendered:
15
16- [flowchart](flowchart.d2) — nodes, edges, decisions
17- [sequence](sequence.d2) — message passing between services
18- [architecture](architecture.d2) — system architecture with nested containers
19- [class](class.d2) — class hierarchy
20- [er](er.d2) — entity relationship diagram
21- [grid](grid.d2) — grid layout
22
23## styling
24
25D2 supports inline styling on any element:
26
27```d2
28server: Web Server {
29  style.fill: "#e8f5e9"
30  style.stroke: "#4caf50"
31  style.border-radius: 8
32}
33```
34
35styled demos:
36
37- [flowchart-styled](flowchart-styled.d2) — custom colors and shapes
38- [architecture-styled](architecture-styled.d2) — themed architecture diagram
39
40## how it works
41
421. push a `.d2` file via git (or save via edit mode)
432. sublimated detects the file type and sends it to the D2 renderer (@terrastruct/d2 WASM)
443. the rendered SVG is stored in CAS as a `render_svg` representation
454. when you view the file, the SVG is displayed inline
465. edit via `~edit` opens CodeMirror, save triggers re-render
476. if rendering fails (invalid syntax), the source is shown as highlighted code
48
49## embedding in markdown
50
51D2 code blocks in markdown files are rendered server-side at push time:
52
53````
54```d2
55server -> database: queries
56```
57````
58
59you can also embed standalone `.d2` files via content block transclusion.
60
61## layout engines
62
63D2 supports multiple layout engines. sublimated uses ELK by default:
64
65- dagre — fast, hierarchical layout (Graphviz DOT-like)
66- ELK — more mature, better port positioning, supports container sizing
67- TALA — proprietary (Terrastruct), best output for architecture diagrams
68
69to specify a layout engine, add a directive at the top of your file:
70
71```d2
72direction: right
73
74# or use vars
75vars: {
76  d2-config: {
77    layout-engine: elk
78  }
79}
80```
81
82## vs mermaid
83
84both are text-based diagram languages. key differences:
85
86- D2 has first-class containers (nested groups) — mermaid's subgraphs are limited
87- D2 supports multiple layout engines — mermaid only uses dagre
88- D2 supports LaTeX equations and syntax-highlighted code blocks inside nodes
89- D2 has better error messages (multi-error, friendly)
90- mermaid has broader platform support (GitHub, GitLab, Notion render it natively)
91- sublimated renders both — use whichever fits your diagram