What is Avodado?

Documentation-as-code. Plain Markdown with typed, fenced YAML blocks. The files on disk are the only source of truth — the CLI, any AI agent, the MCP server, and any UI are all just editors and consumers of those files.

docs/orders.md
─────────────
## 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 }
```

Anywhere prose belongs, it's plain Markdown. Anywhere structure belongs (a diagram, a table, a user story, a chart), it's a fenced block whose info-string is the block type, with a YAML body.

How it works

1. Write docs/*.md — normal Markdown, plus fenced blocks (```sequence, ```erd, ```table…) for anything structured.
2. Check — avo check validates every block's schema and your doc#id cross-references, printing precise, fixable diagnostics (line, column, "did you mean?"). Gate CI on it.
3. Render — avo html / avo preview turn a doc into a styled, self-contained HTML page (6 themes, inline SVG diagrams, no runtime).

The guiding principle

The files on disk are the only source of truth. The CLI, agents, and any UI are editors and consumers of those files; none owns state. The core library turns files into a validated in-memory model with a reference graph; everything else consumes that model.

Humans edit the .md files in any editor; AI agents author them via the bundled skill (avo init) or the MCP server. Same files, many editors.

Start here

Prefer to see it first? Run pnpm dlx @avodado/cli demo in a terminal, browse the live block catalog, or open the demo — a real avo build of this repo's docs.