The block model

Noma documents are trees of typed blocks. Each block knows what it is, what it contains, and how it should render across HTML, PDF, and LLM context.

Anatomy of a block

::claim{id="claim-living-docs" confidence=0.9}
Documentation rots faster than the code it describes.
::

The opener carries the type (claim), an attribute list (id, confidence), and the body content. The closer is a bare :: on its own line. Children get one more colon than their parent — :::card inside ::grid, ::::tab inside :::tabs.

Why typed blocks matter

A claim is not a risk is not a decision. The validator can reason about them differently — claims should have backing evidence, risks should have an owner, decisions should have a status. Themes can render them with different visual emphasis. Agents can patch them by ID without touching unrelated text.

The minimal block set

You can do most real work with about a dozen blocks: section, paragraph, code, list, quote, table, callout, grid, card, claim, evidence, risk, agent_task. The rest are convenience.