Using Claude Code: The unreasonable effectiveness of HTML

HTML vs Markdown as Agent Output

• Many commenters already use LLMs to generate HTML, especially single‑file index.html tools; the novelty is favoring HTML over Markdown for specs and internal docs.
• Pro‑HTML points: richer visuals, interactivity, better dashboards, diagrams, and step‑by‑step “slideshows”; easier to skim and more engaging than long plain Markdown.
• Counterpoints: Markdown is simpler, more readable in raw form, and closer to plain text. For many, HTML adds unnecessary ornamentation and cognitive load.

Human Editing, Collaboration, and Co‑Authoring

• Critics worry HTML docs are harder for humans to co‑author or tweak directly, pushing people to rely on the LLM for every change.
• Others argue basic HTML is easy enough, has been hand‑authored for decades, and modern editors make it manageable.
• Some suggest HTML+contenteditable/WYSIWYG or annotation layers to enable comments and inline edits.

Token Efficiency, Context, and Vendor Incentives

• Multiple comments note HTML is more token‑heavy than Markdown, especially for tables and styled layouts.
• Concern that promoting HTML increases token usage and strengthens vendor lock‑in via HTML‑specific tooling.
• Others observe tooling already optimizes context (grep/awk, partial reads) and see HTML overhead as acceptable when clarity improves.

Use Cases: Dashboards, Specs, and Throwaway Tools

• Popular pattern: “single index.html, no deps” for calculators, dashboards, PR review UIs, and quick internal tools; easily emailed or shared on a static host or tailnet.
• Interactive specs: HTML + JS + SVG used to model systems, verify code behavior, or replay agent sessions as slideshows.
• Several teams now store internal memos/specs as HTML with annotation systems; others generate reports as HTML from experiments or database queries.

Alternatives and Middle Grounds

• Many point out Markdown supports inline HTML, which can deliver most benefits while keeping base docs simple.
• Other suggested formats: GitHub‑flavored Markdown, MDX, AsciiDoc, org‑mode, JSON/XML schemas, Typst pipelines, “richer Markdown” or custom DSLs.
• Some prefer structured JSON/YAML for specs (static analysis, schema validation) and then generate Markdown or HTML for human reading.

Meta‑Discussion and Skepticism

• Some see the article as rediscovering obvious web fundamentals and over‑hyping a trivial HTML vs Markdown choice.
• Others view this as a natural “full circle” moment: HTML again becomes the universal, editable, sharable artifact for both humans and agents.