Your first doc

An Avodado doc is plain Markdown with typed, fenced YAML blocks. Prose stays prose; anything structured — a diagram, a table, a roadmap, a user story — goes in a block that renders to clean HTML, slides, or PDF.

The one rule: the .md file is the source of truth. Edit a block surgically — never regenerate a whole document — and run avo check until it passes. A passing check is the definition of done.

Anatomy of a block

Every block is a fenced code block whose info-string is the block type and whose body is YAML. Give a block an id: when you want to reference it; set a title: so the rendered section reads like a document.

## Request flow

```sequence
id: seq-gs-checkout
title: Place an 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 }
```

That block renders as a real SVG sequence diagram — no runtime JavaScript, just inline SVG in a styled page. Here it is, rendered by the same pipeline avo build uses (the YAML you write on the left, the output on the right):

The everyday workflow

Four steps, over and over: scaffold once, then edit → validate → render.

avo init  ──▶  edit the .md  ──▶  avo check ──ok──▶  preview / studio / build
                    ▲                  │
                    └── fix diagnostics ◀── errors

avo check                    # validate all docs (schema + refs + duplicate ids)
avo preview docs/orders.md   # render to a temp HTML file and open it
avo studio                   # the local surface — Edit visually, browse the live Site, Present slides

avo check exits non-zero on any error and names the file, line, and offending value — see Validation for every diagnostic code and its fix.

Already have the data somewhere else? Import it instead of retyping: avo sync csv sales.csv turns a CSV export into a ready-to-paste table/statustable/chart block (or a whole doc with --out), and dropping the file onto the studio canvas does the same in place.

A few blocks to get the feel

You compose a doc from 2–5 blocks, each a different lens. A KPI strip:

A roadmap as a timeline:

Browse all 77 in the blocks reference — every type with its exact fields and a complete example.

Connect blocks with doc#id

Give a block an id:, then point at it as doc#id (or bare #id in the same file). A dangling reference fails avo check — so the model stays honest.

The full scheme is in References.

Themes and slides

• Themes. Six built-ins (textbook · minimal · soft · dark · teal · slate). Run avo theme to pick one, or avo theme new <name> to craft a custom one. No rebuild — re-render and it's applied.
• Slides. Any doc is a deck: avo slides <file>. Each #/## heading starts a new slide and is its title; everything under it rides along.

Both in depth: Slides & theming.

Next steps

• The block grammar and YAML pitfalls — ten minutes that prevent most validation errors.
• The CLI reference — every command at a glance.
• Avodado Studio — the visual editor over the same files.