When HTML Beats Markdown

1.0 · Decision criteria

Choose HTML when…

At least one of these five conditions must hold. If none do, stay in markdown.

C-01 Side-by-side comparison. The reader needs to compare options, diffs, designs, risks, timelines, or plans next to each other.
C-02 The work has a shape. Architecture, flow, ownership, dependencies, lifecycle, or an incident timeline — spatial structure that linear prose flattens.
C-03 It travels. The artifact will be reviewed in a meeting, printed to PDF, archived, or handed to another implementer.
C-04 Interaction helps. Tabs, filters, toggles, collapsible detail, comments, drag/drop ordering, or copy/export buttons would genuinely serve the user.
C-05 It can be a tool. The output can become a reusable local tool rather than a static answer.

Inverse rule: stay in markdown when the answer is short, linear, or command-like.

2.0 · Comparison matrix

Markdown vs HTML, by situation

Situation	Markdown	HTML	Verdict
Comparing options side by side	Sequential sections; the reader scrolls back and forth to hold both in mind.	Columns, matrices, and decision panels put tradeoffs in one viewport.	HTML
Work with shape / architecture	ASCII diagrams and nested lists approximate structure, poorly.	Inline SVG flowcharts, module maps, ownership lanes, dependency graphs.	HTML
Meeting, PDF, or archive use	Renders differently per viewer; no layout control for print.	One self-contained file with print CSS; opens anywhere, archives intact.	HTML
Interaction needs	Static by definition; no tabs, filters, or collapsible detail.	Browser-native tabs, toggles, accordions, and export controls (per profile).	HTML
Reusable tool	An answer you read once.	A local editor, triage board, or tuner you keep and reopen.	HTML
Short, linear, or command-like answer	Instant to read, trivial to copy, fits the terminal it was born in.	Overhead with no payoff; the file ceremony adds nothing.	MARKDOWN

3.0 · Artifact families

Nine families of HTML artifact

F-01

Exploration & planning

Side-by-side approaches, visual directions, implementation plans with milestones, data flow, risky code, gates, rollback.

F-02

Code review & understanding

Annotated diffs, module maps, file tours, call graphs, reviewer focus lists, severity tags, jump links.

F-03

Design

Tokens, swatches, type scales, spacing systems, component variants, states, and accessibility notes as live surfaces.

F-04

Prototyping

Small clickable flows or animation sandboxes, only when interaction changes the decision. Exportable state if it edits.

F-05

Diagrams

Inline SVG flowcharts, architecture maps, lifecycle diagrams, figure sheets. Readable labels, no decorative complexity.

F-06

Decks

Section slides with arrow-key navigation, progress, print CSS, and dense meeting-ready copy.

F-07

Research & learning

Explainers with TL;DR boxes, collapsible path steps, tabbed code samples, examples, glossary, and FAQ.

F-08

Reports

Status cards, small charts, timelines, proof snippets, shipped/slipped/carryover columns, next-action boards.

F-09

Custom editors

Local-only UI for manipulating data: triage boards, flag editors, prompt tuners, ordering tools. Always with copy/export.

4.0 · Design registers

Pick the register before colors

Operational Dense, scannable, restrained, proof-forward.

Product Efficient repeated use, clear controls, stable states.

Brand Image-led or object-led, strong first viewport, memorable but not noisy.

Learning Calm hierarchy, examples, progressive detail, glossary.

5.0 · Glossary

Terms

Artifact: A single browser-ready HTML file produced from agent or repo context — a brief, plan, map, report, explainer, diagram, prototype, or editor. Stdout, made permanent.
Self-contained: Everything inline: CSS and any permitted JS live in the file. No external fonts, CDNs, assets, analytics, or build step unless the user explicitly asks.
Operator surface: The first viewport, designed for the person running the work: it must reveal the subject, current status, and where attention should go before any scrolling.
Validation profile: The rule set an artifact is checked against. rich for script-free documents, app for artifacts with legitimate inline interactivity, deck for slide decks.
Plate: The signature Hardcopy device: an engineering-drawing title block — a hairline grid of mono-uppercase cells (mode, source, date, counts) that opens documents and footers decks.

6.0 · FAQ

Questions agents and operators actually ask

Why not just markdown?

Often you should — markdown is the correct format for short, linear, command-like answers, and htmlify says so explicitly. HTML replaces markdown only when the work is visual, spatial, comparative, interactive, or reusable in the browser. The five criteria in section 1.0 are the gate; if none apply, an HTML file is ceremony without payoff.

Is the script ban absolute?

No — it is per profile. The rich profile forbids scripts: explainers, briefs, reports, and plans should not need them. The app profile allows inline scripts for artifacts that legitimately carry interactivity — editors, prototypes, triage boards — provided the script is authored directly in the artifact. The deck profile covers slide decks with keyboard navigation. In all cases generated HTML is treated as untrusted until validated.

Can I print these?

Yes — print CSS is required for briefs, reports, plans, and decks, and recommended for anything meant to be shared, archived, or exported as PDF. Under Hardcopy, the paper turns white, crop marks render literally, the plate prints as the document header, and stamps stay grayscale-legible. This page carries its own @media print rules.

What about my own design system?

Yours wins. Hardcopy is the default visual identity, not a mandate: when a project supplies DESIGN.md, brand tokens, or an established design system, those are authoritative and the artifact should be styled with them instead.

How do agents validate output?

With the bundled validator, run before the final response. It checks for a standalone doctype/html/body structure, inline-only assets, profile-appropriate interactivity, and structural soundness. Every reported error must be fixed before the artifact ships; remaining warnings are reported to the user.

shell

npx -y @zakelfassi/htmlify htmlify-answer --validate artifact.html --profile rich