Using Claude Code: The unreasonable effectiveness of HTML

Original Article ↗ Hacker News Discussion ↗

HTML is increasingly being used as the primary output format for AI-generated plans, specs, reports, and internal tools, replacing or augmenting Markdown because it enables rich, interactive single-file artifacts with tables, SVGs, dashboards, and lightweight apps that LLMs can generate easily. Supporters argue this makes complex AI output more readable and actionable for teams, especially when combined with simple hosting or local viewing, while critics point to higher token costs, less readable diffs, security risks, and reduced ease of human co-authoring compared to plain text or Markdown. Many see a middle ground in hybrid approaches—Markdown with embedded HTML, MDX-like formats, or structured JSON/HTML schemas—balancing machine-friendliness, human editability, and visual expressiveness.

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.