Your first doc

An Avodado doc is plain Markdown with typed blocks. Prose stays prose. Anything visual — a diagram, a table, a roadmap — goes in a block.

The one rule: the .md file is the source of truth. Edit it, run avo check, and fix what it reports. When the check passes, you're done.

What a block looks like

A block is a fenced code section. The word after the backticks is the block type, and the body is YAML:

## Request flow

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

Two things keep the YAML short: the heading above the block is its title (no title: needed), and most list items have a terse one-line form — client -> api: POST /orders is a whole message.

Here is that block, rendered by the same pipeline avo build uses. The YAML is on the left — try editing it — and the output is on the right:

The optional id: lets other blocks reference this one.

The everyday loop

Set up once with avo init, then repeat three steps:

edit the .md  ──▶  avo check  ──ok──▶  preview or publish
     ▲                 │
     └── fix what it reports

avo check                    # validate every doc
avo preview docs/orders.md   # render one doc and open it
avo studio                   # edit visually in the browser

avo check names the file, the line, and the problem — see Validation for what each message means.

Already have the data somewhere else? avo sync csv sales.csv turns a CSV into a ready-made table or chart block.

Try a few more blocks

A good doc uses 2–5 blocks, each showing a different side of the topic. A stats strip:

A roadmap as a timeline:

Browse all 87 in the blocks reference — every type has an editable example like the ones above.

Connect blocks with references

Give a block an id:, then point at it from another block with #id (same file) or doc#id (another file). A reference to an id that doesn't exist fails avo check:

More in References.

Themes and slides

• Themes. Six built-in looks (textbook, minimal, soft, dark, teal, slate). Switch with avo theme, or design your own in the theme generator.
• Slides. Any doc is also a deck: avo slides docs/orders.md. Each heading becomes a slide.

Both in depth: Slides & theming.

Next steps

• How blocks work and YAML pitfalls — ten minutes that prevent most validation errors.
• CLI reference — every command at a glance.
• Avodado Studio — the visual editor.