The Unreasonable Effectiveness of HTML
URL: https://thariqs.github.io/html-effectiveness/ Author: Thariq Shihipar Type: Essay + example gallery
Core Argument
Use HTML as primary output format for AI agent work instead of markdown. Self-contained .html files are more readable, interactive, and communicate richer information than equivalent prose or markdown docs.
Problem with Markdown/Text Output
- Dense text walls lose spatial and visual information
- Diffs, diagrams, designs degrade when flattened to text
- Side-by-side comparisons impossible in scrolling prose
- No interactivity: no hover, no collapse, no animation
HTML as Pragmatic Middle Ground
- Richer than markdown
- More maintainable than specialized tools
- Minimal overhead: a handful of section tags and twenty lines of JS
- Self-contained: single file, no build pipeline needed
- Integrates naturally into AI agent workflows
20 Examples Across 9 Categories
- Exploration & Planning: side-by-side approach comparisons
- Code Review: annotated diffs, module maps
- Design: living design systems, component variants
- Prototyping: animation sandboxes, clickable flows
- Diagrams: inline SVG, flowcharts
- Decks: keyboard-navigable presentations
- Research: explainers with collapsible sections, glossaries
- Reports: formatted timelines, charts
- Custom Editors: draggable boards, template tuners
Key Takeaways
- Format determines comprehension: same information in HTML vs markdown is not equivalent
- AI agents default to markdown because training distribution — HTML requires explicit instruction
- Interactivity enables progressive disclosure: collapsible sections, hover definitions
- For agents doing agentic work, HTML is a natural deliverable format