As a on-call engineer, I want to a diagram that fails CI when it drifts from the schema, so that incident docs stay trustworthy under pressure.
v0.42.0 · 87 block types
The AI-first docs-as-code tool.
Describe what you need and your AI agent writes beautiful technical documentation — plain Markdown with typed design blocks. Avodado gives agents the skill to write it and avo check verifies every block. You review and edit anything by hand — in Studio or any editor — then publish it as a site, slides, a PDF, or a PowerPoint deck.
npm install -g avodado
docs/checkout.mdlive
1you prompt
2the agent writes
3rendered live
Docs as code
Write documentation like code.
Keep your documentation next to your code using Markdown and Git. Review changes with pull requests, track every update, and validate your documentation automatically before publishing.
docs/checkout.mdyou write this
```sequence
title: Checkout
actors:
- { id: client, name: Client }
- { id: api, name: Orders API }
- { id: db, name: Postgres }
messages:
- client -> api: POST /orders
- api -> db: INSERT order
- api --> client: 201 Created```
checkout.htmlavo renders this
docs/data-model.mdyou write this
```erd
title: Order data
entities:
- name: users
columns:
- id uuid pk
- email text
- name: orders
columns:
- id uuid pk
- user_id uuid fk
- status text
- name: order_items
columns:
- id uuid pk
- order_id uuid fk
- qty int
relations:
- users ||--o{ orders: places
- orders ||--o{ order_items: contains```
data-model.htmlavo renders this
docs/architecture.mdyou write this
```c4
title: System context
level: context
nodes:
- { id: user, col: 1, row: 1, kind: person, name: Shopper, desc: A customer placing an order. }
- { id: app, col: 2, row: 1, kind: system, name: ShopCo, desc: The retail platform. }
- { id: pay, col: 3, row: 1, kind: external, name: Payment GW, desc: Stripe authorisation. }
edges:
- { from: user, to: app, label: places order }
- { from: app, to: pay, label: authorises }```
architecture.htmlavo renders this
docs/latency.mdyou write this
```chart
title: p95 latency by week
kind: line
unit: ms
labels: [W1, W2, W3, W4]
series:
- { label: /orders, accent: navy, values: [240, 220, 185, 150] }
- { label: /search, accent: teal, values: [310, 285, 260, 230] }```
latency.htmlavo renders this
docs/launch-status.mdyou write this
```statustable
title: Checkout launch
columns: [Workstream, Latest update]
statuses:
- { label: on track, color: green }
- { label: at risk, color: amber }
- { label: blocked, color: red }
rows:
- { cells: [Payment provider migration, Adapter live behind a feature flag], status: on track }
- cells: [Fraud review queue, Model handoff slipped a week]
status: at risk
subtasks:
- { cells: [Rule-based fallback, Serving 10% of traffic today], status: on track }
- { cells: [Tax calculation, Vendor contract still in legal review], status: blocked }```
launch-status.htmlavo renders this
Or see whole documents built this way in the live demo
Work with AI
Create documentation faster with AI.
Let AI help you write, update, and organize your documentation. Avodado gives AI agents structured blocks and clear schemas, so they generate consistent documentation instead of unstructured Markdown — with Claude Code, Cursor, GitHub Copilot, or any AI coding agent.
Teach it once
avo install claudedrops the authoring skill into your repo — the block grammar, the reference scheme, every field contract. Claude Code, Cursor, Copilot, and Windsurf all read it.Tools, not guesswork
The MCP server gives agents seven tools —
get_block_schema,check_document,render_document… — so they look the schema up instead of inventing fields.A safety net for AI edits
Every block validates against a strict schema. An invented field, a dangling reference, a malformed diagram —
avo checkfails it on the spot, and in CI.Review it like code
The output is a Markdown diff, not an exported canvas. AI-written docs go through the same pull-request review as AI-written code — because they validate the same way.
● Edited docs/webhooks.md — added a ```sequence blockdocs/webhooks.md:18 E_SCHEMA unknown field 'retries'● not in the schema — fixed: retry loop as explicit messagesOK: 4 files checked, no diagnosticsdocs that survive their own review — commit itHow it works
From an idea to polished documentation.
Write in Markdown or ask your AI agent. Add Avodado blocks for diagrams, architecture, APIs, and project updates. Validate to catch invalid content and broken references. Then publish a website, slides, a PDF, or a PowerPoint deck — all from the same files.
docs/system-overview.mdsystem-overview.md
docs/cloud.mdcloud.md
docs/roadmap.mdroadmap.md
parse · validate · resolve
HTML site
Slides
PDF · PPTX
Studio
MCP · AI
Design blocks
Make your documentation look great.
Add beautiful, ready-to-use blocks directly inside your Markdown — architecture diagrams, timelines, API docs, roadmaps, cards, charts, status reports, and more, without designing every page by hand.
Document coverCalloutTableSequence diagramEntity-relationship diagramUser storyTimelineKanban boardStructured proseGlossaryPros & consCurrent vs targetKPI cardsCode snippetsMeeting agendaFile treePyramidFlowchartState machineData-flow diagramUser journeyGantt chartNode-link graphQuadrant chartSwimlane diagramC4 architectureUML class diagramComponent treeCluster topologyBlock diagramFrontend logic graphWireframeAPI endpointPull quoteLayered explanationCapability matrixAnatomy breakdownAccess compositionDesign driversOptions consideredSpec sheetFancy listStory backlogDesign pattern
Document coverCalloutTableSequence diagramEntity-relationship diagramUser storyTimelineKanban boardStructured proseGlossaryPros & consCurrent vs targetKPI cardsCode snippetsMeeting agendaFile treePyramidFlowchartState machineData-flow diagramUser journeyGantt chartNode-link graphQuadrant chartSwimlane diagramC4 architectureUML class diagramComponent treeCluster topologyBlock diagramFrontend logic graphWireframeAPI endpointPull quoteLayered explanationCapability matrixAnatomy breakdownAccess compositionDesign driversOptions consideredSpec sheetFancy listStory backlogDesign pattern
Document coverCalloutTableSequence diagramEntity-relationship diagramUser storyTimelineKanban boardStructured proseGlossaryPros & consCurrent vs targetKPI cardsCode snippetsMeeting agendaFile treePyramidFlowchartState machineData-flow diagramUser journeyGantt chartNode-link graphQuadrant chartSwimlane diagramC4 architectureUML class diagramComponent treeCluster topologyBlock diagramFrontend logic graphWireframeAPI endpointPull quoteLayered explanationCapability matrixAnatomy breakdownAccess compositionDesign driversOptions consideredSpec sheetFancy listStory backlogDesign pattern
Document coverCalloutTableSequence diagramEntity-relationship diagramUser storyTimelineKanban boardStructured proseGlossaryPros & consCurrent vs targetKPI cardsCode snippetsMeeting agendaFile treePyramidFlowchartState machineData-flow diagramUser journeyGantt chartNode-link graphQuadrant chartSwimlane diagramC4 architectureUML class diagramComponent treeCluster topologyBlock diagramFrontend logic graphWireframeAPI endpointPull quoteLayered explanationCapability matrixAnatomy breakdownAccess compositionDesign driversOptions consideredSpec sheetFancy listStory backlogDesign pattern
Card galleryData chartFigureHow-to stepsFAQBack-of-envelope mathSLOs & error budgetsSWOT analysisOKRsUser personasChangelogTeam cardsHeatmapDecision scorecardRisk registerColor paletteType scaleDo / don't guideComponent inventoryArray walkthroughLinked listBinary treeHash mapAgent loopAgent tracePrompt anatomyContext-window budgetCapability mapSection dividerBig numberTakeawaysStatus tableCycleBenchmark tableFlow volumesBranch graphTreemapPacket layoutVenn overlapWardley mapRated comparisonExecutive summaryScenario table
Card galleryData chartFigureHow-to stepsFAQBack-of-envelope mathSLOs & error budgetsSWOT analysisOKRsUser personasChangelogTeam cardsHeatmapDecision scorecardRisk registerColor paletteType scaleDo / don't guideComponent inventoryArray walkthroughLinked listBinary treeHash mapAgent loopAgent tracePrompt anatomyContext-window budgetCapability mapSection dividerBig numberTakeawaysStatus tableCycleBenchmark tableFlow volumesBranch graphTreemapPacket layoutVenn overlapWardley mapRated comparisonExecutive summaryScenario table
Card galleryData chartFigureHow-to stepsFAQBack-of-envelope mathSLOs & error budgetsSWOT analysisOKRsUser personasChangelogTeam cardsHeatmapDecision scorecardRisk registerColor paletteType scaleDo / don't guideComponent inventoryArray walkthroughLinked listBinary treeHash mapAgent loopAgent tracePrompt anatomyContext-window budgetCapability mapSection dividerBig numberTakeawaysStatus tableCycleBenchmark tableFlow volumesBranch graphTreemapPacket layoutVenn overlapWardley mapRated comparisonExecutive summaryScenario table
Card galleryData chartFigureHow-to stepsFAQBack-of-envelope mathSLOs & error budgetsSWOT analysisOKRsUser personasChangelogTeam cardsHeatmapDecision scorecardRisk registerColor paletteType scaleDo / don't guideComponent inventoryArray walkthroughLinked listBinary treeHash mapAgent loopAgent tracePrompt anatomyContext-window budgetCapability mapSection dividerBig numberTakeawaysStatus tableCycleBenchmark tableFlow volumesBranch graphTreemapPacket layoutVenn overlapWardley mapRated comparisonExecutive summaryScenario table
87 typed blocks
Sequence diagrams, ERDs, C4, kanban boards, charts, user stories — every block has a strict schema and a ready template.
docs/hello.md:10 E_SCHEMA
sequence: unknown field 'idempotent'
docs/hello.md:12 E_DANGLING_REF
Dangling reference: "orders#seq-place-order" (target not found)
docs/hello.md:1 W_SUSPECT_BLOCK
`sequnce` looks like a typo of `sequence` — rendered as plain text
Strict validation
avo check names the file, line, and offending value — and exits non-zero. Gate CI on it.
```userstory
links:
- { ref: orders#seq-place-order }
```
Cross-references
Give a block an id, reference it as doc#id from anywhere. Duplicate ids and dangling refs are caught repo-wide.
textbook
minimal
teal
slate
dark
soft
6 themes
Rendered pages and decks pick up any of the built-in themes — same content, different paper.
## Findings {split}
Slides from the same file
One slide per heading, keyboard navigation, PDF and PowerPoint export. A {split} marker gives message-left, exhibit-right.
get_authoring_guidelist_block_typesget_block_schemacheck_documentrender_documentresolve_refssync_openapi
get_authoring_guidelist_block_typesget_block_schemacheck_documentrender_documentresolve_refssync_openapi
get_authoring_guidelist_block_typesget_block_schemacheck_documentrender_documentresolve_refssync_openapi
get_authoring_guidelist_block_typesget_block_schemacheck_documentrender_documentresolve_refssync_openapi
avo install claudeClaude CodeCursorGitHub CopilotWindsurf.avodado/skill/SKILL.md
avo install claudeClaude CodeCursorGitHub CopilotWindsurf.avodado/skill/SKILL.md
avo install claudeClaude CodeCursorGitHub CopilotWindsurf.avodado/skill/SKILL.md
avo install claudeClaude CodeCursorGitHub CopilotWindsurf.avodado/skill/SKILL.md
AI-native
An authoring skill plus an MCP server — agents write, check, and render the same files you do, through seven tools.
avo studio
Write in Markdown or edit visually.
Use the CLI for a documentation-as-code workflow, or open Avodado Studio for a more visual editing experience. Your Markdown always remains the source of truth.
‹ Homedocs/orders.md▶ PresentSite ↗localhost:4174
sequence · selected
avo studio — click a block to select it, edit it as a form or as YAML, and watch the preview update. The document above is real rendered output, not a screenshot.
Open Studio in your browser
No signup, no install — the whole editor runs in the tab, and nothing is uploaded.
The catalog
A block for every shape of thought
Each miniature below is a real render of that block's built-in template — the same starting point avo gives you.
Browse all 87 block types
0
block types
0
families
0
themes
0
tests
The gallery
All of this is plain text.
Nine documents, six themes, zero screenshots — every sheet below is a fenced YAML block rendered at build time by the same pipeline avo build runs. Open devtools: it's live SVG.
Start creating better documentation.
Write it with Markdown. Generate it with AI. Make it beautiful with Avodado blocks.
npm install -g avodado