The block grammar

Avodado documents are plain Markdown with typed, fenced YAML blocks. Prose is ordinary Markdown; anything structured (a diagram, a table, a user story, a chart) is a fenced code block whose info-string is the block type, with a YAML body.

The one rule: the .md file is the source of truth. You edit files directly. A document must read fine as plain text with no tooling, so never paste raw HTML or inline SVG — express structure through blocks instead.

How a block looks

## Request flow

```sequence
id: seq-place-order
title: Place order
endpoint: { method: POST, path: /orders }
actors:
  - { id: Client, name: Client }
  - { id: API, name: Orders API }
messages:
  - { from: Client, to: API, label: POST /orders, kind: sync }
  - { from: API, to: Client, label: 201 Created, kind: response }
```

The rules

• The info-string is exactly one of the 77 block types — never invent new ones. The full map lives in the blocks reference; the exact field contract for every block is the contract page.
• The body is YAML (JSON is also accepted; YAML is preferred — prefer block-style over deep inline maps for readability and clean diffs).
• Use only the fields documented for that block — the schemas are strict; unknown fields are rejected. Keep prose outside blocks.
• A block MAY carry a top-level id: (a slug) so other blocks can reference it.
• Most diagram blocks accept optional title, description, and lede — these surface in the section header + diagram frame around the SVG.

One heading per idea

A ## heading immediately followed by a block whose title says (nearly) the same thing renders as two stacked headings — keep one. Either drop the block title (the heading already names it) or make the heading say something the title doesn't. avo check flags this as W_DUP_HEADING.

Do / Don't

Do

• Edit the specific block you need to change — surgically, a few lines — rather than regenerating a whole document.
• Keep narrative in Markdown prose and structure in blocks.
• Use title + lede on diagram blocks so the section header reads well.
• Quote YAML values that contain commas, colons, or 1:N cardinality strings (desc: "40 blocks, themes, agent skill", card: "1:N") — see YAML pitfalls.
• Give a block an id: whenever something else might reference it.
• Run avo check and resolve all diagnostics before finishing.
• When unsure which architecture block to use, pick block for boxes-and-arrows or c4 for actor / system context — both are safe defaults.

Don't

• Paste raw HTML, <svg>, or <style> into a doc. Use blocks.
• Invent block types or fields. The schemas are strict; unknown fields error.
• Reference a doc#id that doesn't exist. Either fix the ref or add the id.
• Stuff a whole spec into one giant block. Decompose into 3–5 focused blocks.
• Write a description longer than 2 sentences. Use prose instead for long narrative.
• Reuse the same id: in two blocks. Ids are repo-global unique.
• Add a prose block AND raw ## headings for the same idea. Pick one.

Mixing blocks

A good Avodado doc is 2–5 blocks, each a different lens on the subject — orient → big picture → detail → plan. Don't show the same thing in two block types, and don't reach for all 77:

Most playbooks ship as a ready skeleton: avo template <name> scaffolds a valid starting doc — adr, design-doc, runbook, roadmap, api-spec, system-design, agent-system, design-system, postmortem, data-model, deck.

The complete authoring method — intake questions, outlining, block casting, document playbooks — ships with the repo as the authoring skill, which avo init installs into your project for AI agents to follow.