How blocks work

An Avodado doc is plain Markdown with typed blocks. Prose is ordinary Markdown. Anything visual — a diagram, a table, a chart — is a fenced code section whose language tag is the block type, with a YAML body.

## Request flow

```sequence
endpoint: { method: POST, path: /orders }
actors:
  - { id: client, name: Client }
  - { id: api, name: Orders API }
messages:
  - client -> api: POST /orders
  - api --> client: 201 Created
```

Notice what's not there: no title: in the YAML. The heading above a block is its title. Write the heading once and the renderer uses it for the block — no duplication.

The rules

There are only five:

1. The type must be one of the 87 block types. Don't invent new ones.
2. The body is YAML. Use only the fields documented for that block — the schemas are strict, and unknown fields are rejected.
3. Prose stays outside blocks. Never paste raw HTML or SVG into a doc; use a block instead.
4. id: is optional — add one when another block should reference this one. Ids must be unique across the whole repo.
5. The heading titles the block. A ## heading directly above a block becomes its title, so you rarely need title: in the YAML. Diagram blocks also take optional description and lede.

Write less YAML

Most list items have a terse one-line string form. The object forms still work and mix freely — the terse form just expands at parse time:

# Sequence messages — from -> to: label
messages:
  - client -> api: POST /orders
  - api --> client: 201 Created

# Diagram nodes — a bare name is both id and label
nodes: [Receive, Lookup, Ack]
edges:
  - Receive -> Lookup: by key
  - Lookup -> Ack

# ERD columns — name type flags
columns:
  - id uuid pk
  - org_id uuid fk
  - email text

# Glossary, FAQ, takeaways — lead — detail
terms:
  - SLO — the target the team commits to
  - Saga — a long transaction split across services

And callout / pullquote fences can hold just the text — no YAML at all, with inline Markdown (bold, code, links) rendering inside:

```callout
Clients must send an **Idempotency-Key** header, so retries are safe.
```

Let diagrams place themselves

Give a flow, c4, state, dfd, block or felogic just nodes and edges — no col/row — and the layout comes from the graph. It runs left to right, because a stack of ranks down the page outgrows both the page column and a slide:

dir: TB     # only if you want the top-to-bottom layout instead

Placing nodes yourself still wins over everything: with col/row on the nodes, dir does nothing, so put the progression on col and let branches drop to row: 2.

Blocks a deck is built from

Beyond the diagrams, a handful of blocks exist for the argument a deck makes: scqa (situation → complication → question → answer), harvey (a rated comparison with Harvey balls and a computed weighted row), scenarios (base / upside / downside against the same drivers), benchmark (measured results, best-in-row derived) and sankey (how much moves between stages). A tree whose nodes carry value reads as a driver tree — each node's share of its parent, computed.

Do

• Edit the block you need to change — a few lines — instead of regenerating a whole document.
• Quote YAML values that contain commas or colons: desc: "40 blocks, themes, agent skill", card: "1:N". See YAML pitfalls.
• Give a block an id: when something else might reference it.
• Run avo check before you finish. Fix everything it reports.
• Unsure which architecture block to pick? block for boxes-and-arrows, c4 for system context. Both are safe defaults.

Don't

• Don't invent block types or fields — validation will reject them.
• Don't repeat the heading as a title: — the heading already titles the block.
• Don't reference an id that doesn't exist.
• Don't stuff a whole spec into one giant block. Use 3–5 focused blocks.
• Don't reuse an id: — ids are unique across the repo.
• Don't write long prose inside a block's description. Two sentences max; longer narrative belongs in Markdown.

Which blocks for which doc?

A good doc is 2–5 blocks, each a different view of the subject. Some starting points:

Even faster: avo template <name> scaffolds a complete valid doc — eighteen of them, from adr and design-doc to migration-plan, threat-model and service-overview. Each is a finished example about a plausible system, so you edit content rather than fill in a shape. Browse them all on Templates, or open one in Studio with no install.