Source
What humans and agents edit. Markdown is strong here for prose; raw HTML is usually too noisy. Noma keeps the source plain text but adds explicit blocks and stable IDs.
Noma Comparison Guide
Use this guide to decide when Noma is the right source format and when Markdown, MDX, raw HTML, or collaborative docs are still the better choice. The short version: Markdown is still best for simple prose, HTML is still best as the browser artifact, and Noma wins when one durable source must stay readable, render richly, and remain safe for agents to edit block by block.
The short version
| If you need | Use | Why |
|---|---|---|
| Simple prose, README notes, short docs | Markdown | Lowest ceremony and universal tooling. |
| React components inside docs | MDX | Best when the source is already code-adjacent. |
| Pixel-perfect handcrafted pages | HTML | The browser's native language is still the right escape hatch. |
| Comments, approvals, and live co-editing | Google Docs / Notion | Human workflow beats source control for some teams. |
| Agent-editable rich artifacts | Noma | Stable block IDs, typed directives, validation, HTML/PDF/LLM outputs. |
The source-artifact-agent split
The format debate is easier when the three surfaces are separated.
Artifact
What readers consume. HTML is strong here: layout, navigation, diagrams, controls, and shareability. Noma renders HTML instead of asking authors or agents to hand-maintain it.
Agent
What tools need. Agents need predictable IDs, validation, scoped context, and patch operations. Noma exposes these directly instead of making agents infer structure from prose.
Noma vs Markdown
Markdown is still the best default for linear prose. Noma starts to pay for itself when the document needs semantic blocks, table-heavy structure, charts, validation, or agent-safe edits.
| Capability | Markdown | Noma | Why it matters |
|---|---|---|---|
| Plain-text readability | ✓ | ✓ | Both review well in Git. |
| Headings, lists, code | ✓ | ✓ | Noma keeps the familiar baseline. |
| Cards, grids, tabs | ad hoc | native | Rich docs do not need raw HTML. |
| Complex tables | fragile | structured | Pipe tables work for small cases; ::table, datasets, and plots cover larger ones. |
| Claims, evidence, decisions | ad hoc | native | Semantics become queryable and validated. |
| Charts and datasets | external | native | Numbers live with the narrative. |
| Stable agent patch targets | weak | native | Agents can edit one block instead of rewriting the file. |
| Deterministic LLM export | basic | scoped | Context can omit unsafe escape hatches and preserve structure. |
Table-heavy documents
Tables are where Markdown's readable-source promise breaks first. A small comparison table is fine. A 20-row API parameter table, research matrix, decision grid, or financial summary quickly becomes a pipe-and-padding maintenance problem.
Noma keeps three levels:
| Shape | Use it when | Noma support |
|---|---|---|
| Pipe table | The table is small and still readable in source | GitHub-style table parser and noma fmt |
::table directive | Separator rows and padding make the source noisy | Compact rows plus declared alignment |
::dataset + ::plot | The values matter beyond one rendered table | Validated columns, reusable data, HTML plots, LLM export |
Noma vs MDX
MDX is excellent when the author is comfortable writing JSX and the site already has a React build pipeline. Noma is better when the source should remain approachable to non-engineers and agents.
Choose MDX when
- The document is part of a React app.
- Components are the main authoring primitive.
- Authors are comfortable debugging bundler/runtime errors.
- The rendered site is more important than a stable plain-text document contract.
Choose Noma when
- The source must stay readable in any editor.
- Agents need stable IDs and patch operations.
- The same source should render to HTML, PDF, JSON, and LLM context.
- Validation matters more than component expressiveness.
Noma vs raw HTML
HTML is a great output format and a poor long-term source format for agent collaboration. The 2026 agent-output debate made the tradeoff visible: HTML gives agents visual density, diagrams, navigation, and one-off tools, but it is harder to co-author by hand, review in diffs, and safely re-consume as context.
Noma keeps the useful part: render HTML as the artifact. It avoids the weak part: making raw HTML the source of truth.
| Need | Raw HTML | Noma |
|---|---|---|
| Beautiful browser output | ✓ | ✓ |
| Human-readable source | — | ✓ |
| Small Git diffs | — | ✓ |
| Agent-safe block updates | — | ✓ |
| Built-in validation | custom | ✓ |
| Escape hatches when needed | native | controlled |
Noma vs collaborative docs
Google Docs and Notion are better for live human collaboration, comments, and approvals. Noma is better when the document is source-controlled, rendered in CI, consumed by agents, or shipped as a durable artifact.
Decision checklist
Use Noma when at least three are true:
- The artifact needs layout, tables, plots, callouts, or semantic blocks.
- The source must remain readable in plain text.
- An agent will update targeted sections over time.
- You need deterministic LLM context export.
- You want validation to catch stale citations, broken references, or malformed blocks.
- You need HTML and PDF outputs from one source.
Do not use Noma when:
- A plain Markdown file is enough.
- A WYSIWYG workflow is the real requirement.
- The page needs arbitrary app logic as its primary purpose.
- A live collaborative editor matters more than source control.