The book
Writing a page: diagrams, charts and embeds
Every page in the book is plain markdown, and the book turns it into tables, boards, journeys, diagrams and charts. There is no special editor and no custom syntax: write the right markdown or the right named fence, and the visual appears.
The body of a block is the source of truth, for people and AI alike. The Source view edits it as text; the book renders it; an AI reads and writes the same string over MCP. Because it is markdown, it also reads cleanly in an export or a terminal.
Two rules for every visual
- The visual has to carry information the prose does not. A chart of two points or a diagram of two boxes is worse than the sentence it replaced.
- Never invent the numbers or the boxes. If nothing measures it yet, write the prose and name what should be measured. A made-up trend looks like evidence.
Shapes: structure from plain markdown
Some block types are drawn as a board or a timeline, straight from headings, lists and tables.
| Shape | Used by | Write it as |
|---|---|---|
| Timeline | journey_map, roadmap | An H2 per phase, then a table with the columns Step, Happiness, Actions, Experience, Insights |
| Canvas | Business model canvas, SWOT, Porter's five forces, OGSM | An H2 per zone with the conventional zone name, a bullet per card |
| Kanban | kanban_board | An H2 per column, a bullet per card |
| Tree | ia_tree, taxonomy | Nested bullets, with an optional route per node: - Products (/products) |
A journey phase looks like this. Happiness takes one of 😀 🙂 😐 🙁 😣, and the book draws the lanes straight across the journey:
## Discover
| Step | Happiness | Actions | Experience | Insights |
|---|---|---|---|---|
| Hears about it | 🙂 | Reads a colleague's post | Curious, not convinced | Proof from peers matters |
| Visits the site | 😐 | Looks for pricing | Can't find it quickly | Pricing is the first question |
A roadmap phase can carry its milestone as a Done when: line directly under the phase heading. A canvas zone that matches no conventional name still renders, below the framework, so nothing you write is lost.
Diagrams with ~~~flow
A ~~~flow fence holds YAML with nodes and edges. Each node has an id, a label and a role: person, system, external, db, container, component, process, decision, start or end. The book renders it as an SVG diagram; Mermaid is not supported.
~~~flow
title: How a write reaches the brain
direction: LR
nodes:
- { id: dev, label: Developer, role: person }
- { id: ai, label: Claude Code, role: external }
- { id: ec, label: Epic Context, role: system }
- { id: db, label: The graph, role: db }
edges:
- { from: dev, to: ai, label: asks }
- { from: ai, to: ec, label: "update_block, with a reason" }
- { from: ec, to: db, label: stores a new version }
~~~
directionisLR,TB,RLorBT.- For architecture, add
level: context,containerorcomponent, atechnologyon nodes and edges, andgroupsfor boundaries; the book then draws C4 notation with a key. - For a process with stages or teams, use
groupswithkind: laneand put each node in one withgroup:. - Keep a diagram to about twelve nodes. More is two diagrams pretending to be one.
Charts with ~~~chart
~~~chart
title: Weekly active projects
kind: line
unit: projects
target: { value: 40, label: Goal }
categories: [W1, W2, W3, W4]
series:
- { name: Active, values: [12, 15, 19, 23] }
~~~
kind is line (rising or falling?), column or bar (how do a few things compare?), stacked (what is the total made of?) or donut (how did one period split?). Set unit once on the chart, set a target wherever a goal exists, and write a missing period as n/a, never as 0.
A plain markdown table of periods and numbers is charted automatically beside the table, when every cell in a column is a number and there are at least two rows. Keep commentary in its own column.
Embeds with ~~~embed
To show another block inside this page, drawn through its own template, embed it by key:
~~~embed
block: primary-persona
caption: Who this feature is for
~~~
An embed is resolved live, so editing the source block updates every page that embeds it. Add collapsed: true for a long reference.
The Design group's fences
The brandbook pages have fences of their own, in YAML: ~~~palette for colours (swatches with their contrast), ~~~type for typefaces, ~~~scale for space, radius, borders, shadows, type sizes and motion, ~~~gallery for images on a ground, ~~~dodont for a do and a don't, and ~~~theme (in the visual identity only) for the colours and fonts of the Design pages. The schema gatekeeper checks them when the block is saved.
Everything else is ordinary markdown
- Headings, lists and tables, as in any GitHub-flavoured markdown.
- Code samples in fenced blocks with a language tag, for example
```tsor```sql. - Images as
. - Links to other blocks by bare key:
[the pricing decision](adr-012-pricing).
Both fence styles work: ~~~flow and ```flow.
Next
- Book, Source and Map: where the page is read and edited.
- Writing for AI agents: what makes a page useful to an AI.
- Relations: references and typed links between pages.
Last updated: