For years, Markdown has quietly been the default language of collaboration between humans and AI.

We ask coding agents to create implementation plans, summarize pull requests, explain architectures, document decisions, and produce technical reports. Most of the time, the answer comes back in Markdown: headings, bullets, tables, code blocks, and maybe a diagram if the model feels generous.

And honestly, that made sense.

Markdown is lightweight, readable before rendering, easy to version, friendly to Git diffs, and simple enough for both humans and models to write. It became the natural interface between developers and AI agents because it sits in a useful middle ground: structured enough to be practical, but not so complex that it gets in the way.

But a recent discussion around Claude Code challenged that default.

The argument was simple, but interesting: maybe Markdown is not always the best format for AI generated outputs. Maybe, in some situations, HTML is a better medium, especially when the goal is not just to produce text, but to help people understand, navigate, and act on complex information.

At first glance, this sounds like a formatting debate.
It is not.

The real question is about how AI agents should communicate complex work. Should they produce plain, durable, versionable documents? Or should they generate richer, more visual artifacts that feel closer to small applications than static notes?

As usual in software, the answer is not “HTML wins” or “Markdown wins.”
The more useful answer is: they solve different problems.

The Case for HTML: From Text Output to Interactive Artifact

The strongest argument for HTML is not that it looks better.

It is that HTML changes what the output can become.

A Markdown document is usually linear. You scroll from top to bottom. You read a heading, then a paragraph, then a list, then a code block. That works well for short explanations, READMEs, ADRs, technical notes, and implementation summaries.

But once the output gets larger, that structure starts to show its limits.

Think about a multi step implementation plan, a pull request review, a system architecture analysis, a database migration strategy, a product decision matrix, or an incident report. These are not always best consumed as a long vertical document. Sometimes the information has relationships, layers, tradeoffs, flows, and dependencies that are difficult to express in plain text.

That is where HTML becomes interesting.

A code review can become an annotated diff with severity indicators, jump links, and grouped findings. A system explanation can become a clickable module map. An architecture decision can become a comparison grid with risks, constraints, dependencies, and diagrams. A research summary can include collapsible sections, tabs, glossary terms, and interactive examples.

This is not only formatting.
It is workflow design.

For visual, spatial, or interactive topics, HTML can communicate things that Markdown can only describe. A paragraph can explain a flow. A diagram can show it. A clickable diagram can let the reader explore it.

That difference matters because AI generated outputs are often written for humans who are busy, distracted, and trying to make decisions quickly.

A long Markdown file may be complete and still fail at its real job: helping someone understand what to do next.

HTML can help close that gap.

The Community Reaction: Interested, but Skeptical

The community reaction to this idea has been mixed, and that is probably a good thing.

Many people immediately understood the value of HTML for final outputs, visual reports, prototypes, and interactive artifacts. At the same time, there was strong resistance to the idea of making HTML the default format for agent communication.

That skepticism is not just conservatism. It comes from real workflow concerns.

One of the strongest counterarguments is that HTML does not necessarily solve the root problem. If an AI agent generates a massive implementation plan that nobody wants to read, maybe Markdown is not the issue. Maybe the agent simply wrote too much.

In other words, HTML can make a bloated output more attractive, but it does not automatically make it better.

A 2,000 line HTML file with tabs, cards, CSS, JavaScript, and SVG diagrams may be more pleasant to open in a browser than a 2,000 line Markdown file. But if the reasoning is weak, the structure is unclear, or the recommendations are vague, the format will not save it.

That is one of the most important points in this discussion:

Better presentation is not a substitute for better thinking.

There is also a practical developer concern. Markdown is easy to inspect. HTML is often easier to consume after rendering, but harder to review as source.

That difference matters.

A Markdown file can be reviewed directly in a pull request. A generated HTML file may require the reviewer to mentally separate content, layout, styling, scripts, and presentation choices. The rendered page may look polished, while the underlying source is noisy and difficult to maintain.

That is why many developers seem open to HTML as a delivery format, but far less comfortable with HTML as the default working format.

The Markdown Argument: Source of Truth Still Matters

Markdown’s biggest advantage is not beauty. It is operational simplicity.

It works almost everywhere. It is readable before rendering. It is easy to edit. It works well with Git. It is easy to review in pull requests. It can be searched with simple tools. It can be generated, transformed, linted, converted, and embedded into documentation sites.

That may sound boring, but boring is often what makes a format reliable.

Many AI agent outputs are not disposable. Architecture decisions, implementation plans, product specs, runbooks, postmortems, onboarding guides, and API documentation often need to live in a repository. They need to be reviewed by people. They need to survive beyond the first AI interaction. They may need to be updated months later by someone who never saw the original prompt.

For that kind of work, Markdown is still hard to beat.

Markdown keeps content and presentation reasonably separate. That separation is valuable in software engineering because it keeps the source clean, portable, and easy to reason about.

HTML, on the other hand, often mixes content, layout, styling, and behavior into the same artifact. That can be powerful, but it also makes the result harder to maintain.

A beautiful HTML artifact may be perfect for a workshop or stakeholder presentation. But if someone needs to update a single section later, they may have to navigate nested divs, CSS classes, layout structures, inline styles, and embedded scripts.

That is not a small detail.
It is a maintenance cost.
Markdown is boring in the best possible way.
It is durable.

The Token Question: Beauty Has a Cost

The token discussion is not just theoretical.

LLM APIs are priced by tokens, and output format directly affects token usage. Markdown is compact. HTML adds tags. Styled HTML adds CSS. Interactive HTML adds JavaScript. Diagram heavy HTML may include inline SVG. A beautiful, standalone artifact can easily become much larger than the equivalent Markdown document.

For one document, this may not matter.

For a team generating dozens or hundreds of artifacts per week, it starts to matter. It affects cost, latency, context usage, rate limits, and agent responsiveness.

To make this more concrete, imagine an AI agent producing an implementation plan and generating it with Claude Sonnet 4.6. At the time of writing, Anthropic lists Claude Sonnet 4.6 output pricing at $15 per million output tokens.

These numbers are illustrative, not universal. Tokenization depends on the model, the content, the markup style, and whether the HTML includes CSS, JavaScript, SVG, or embedded data. The cost also changes depending on the model used. A cheaper model may reduce the financial impact, while a more expensive model may amplify it.

Still, the principle is clear:

HTML gives you more expressive power, but that power is paid for in tokens, latency, and complexity.

That does not mean HTML should be avoided. It means HTML should be intentional.

If the output is a simple implementation note, Markdown is probably enough. If the output is an executive facing architecture walkthrough with diagrams, comparisons, and navigation, the extra token cost may be justified.

The question is not whether HTML costs more.

It usually does.

The real question is whether the extra cost produces enough extra value.

Reviewability and Security

There is another important dimension here: reviewability.

Markdown is transparent. What you see in the source is close to what you get in the rendered output. HTML is different. The rendered page may look simple, while the source may contain hidden elements, scripts, styles, remote assets, or behavior that is not obvious at first glance.

For personal experiments, that may be fine.

For enterprise environments, it matters.

Generated HTML should be treated as code, not just as a document. It may include JavaScript. It may include event handlers. It may include external references. It may include hidden text. It may include styling tricks that change what the reader sees versus what another system or agent might parse.

That does not make HTML dangerous by default. It simply makes it more powerful, and powerful formats require more discipline.

A reasonable set of rules could look like this:

• Generated HTML reports should be static by default.
• External scripts and remote assets should be avoided unless explicitly needed.
• HTML artifacts should not become the source of truth unless the team is prepared to maintain them.
• Important decisions should still be captured in a simpler canonical format.
• Generated HTML should be reviewed like code when it enters a repository.

In other words, HTML can be a great output format, but it should not be treated as harmless plain text

Choosing the Right Format: Markdown for Truth, HTML for Experience

A better way to frame the decision is not to ask whether HTML is better than Markdown, but to ask what role the output is supposed to play.

If the artifact needs to become part of the team’s long term knowledge base, Markdown is usually the safer choice. It works well for technical documentation, ADRs, READMEs, runbooks, implementation notes, pull request descriptions, meeting notes, and architecture decisions. These are artifacts that people may need to review in Git, edit manually, search with simple tools, or revisit months later.

Markdown is not exciting, but that is exactly why it works. It is predictable, portable, and durable. It keeps the focus on the content rather than the presentation.

HTML becomes more valuable when the goal is communication, exploration, or decision making. If the output needs to help someone quickly understand a complex system, compare alternatives, navigate a flow, or interact with a prototype, HTML can offer a much better experience.

This is where HTML shines: executive architecture summaries, interactive system diagrams, rich code walkthroughs, visual pull request reviews, incident timelines, status reports, design system previews, clickable prototypes, comparison dashboards, workshops, and temporary tools that can export back to Markdown, JSON, or YAML.

In short, Markdown is the better format when the output needs to be maintained. HTML is the better format when the output needs to be experienced.

A Better Mental Model: Source Format vs. Delivery Format

The mistake is treating this as a binary decision.
It should not be “Markdown or HTML.”

It should be:

• What is the source of truth?
• What is the best delivery experience?

For source of truth, Markdown often wins. So do JSON, YAML, OpenAPI, AsyncAPI, ADR templates, database schemas, and structured domain models.

For delivery, HTML can be excellent.

This pattern is already familiar in software architecture. We separate data from presentation. We separate domain models from UI. We separate canonical schemas from consumer specific formats.

AI agent outputs should follow the same principle.

A practical workflow could look like this:

1. Ask the agent to reason and store the canonical result in Markdown, JSON, or YAML.
2. Review and version that source artifact.
3. Generate HTML only when the goal is presentation, exploration, or stakeholder communication.
4. Treat HTML as a rendered view, not necessarily the source of truth.

This gives us the best of both worlds.
Markdown remains the maintainable layer.
HTML becomes the experience layer.

The Enterprise Perspective

In enterprise environments, this distinction becomes even more important.

Executives, product leaders, architects, engineers, and operations teams do not consume information in the same way.

A developer reviewing an implementation plan may prefer Markdown because it is precise, diffable, and close to the codebase. An executive reviewing a modernization strategy may prefer an HTML artifact with diagrams, decision points, timelines, and tradeoff summaries. A platform team may want a JSON or YAML source that can generate both formats.

This is where AI agents can become much more useful.

Instead of asking an agent for one universal output, teams can ask for layered outputs:

• A canonical Markdown decision record.
• A structured JSON summary of risks and dependencies.
• An HTML executive view.
• A slide deck or PDF for distribution.
• A checklist for implementation tracking.

The agent does not need to choose one format forever. It can generate different representations for different audiences.

That is a more mature way to think about AI assisted work.
The future is not one format.
The future is format aware generation.

My Opinion: HTML Is Not the New Markdown

The most reasonable position is not that HTML should replace Markdown.

It should not.

Markdown is still the better default for maintainable technical knowledge. It is more transparent, more editable, more diffable, and more efficient.

But HTML deserves a bigger role in AI agent workflows.

When an agent is helping us understand complexity, communicate tradeoffs, explore alternatives, or present ideas to a team, HTML can turn a passive document into an active interface.

That is valuable.

The key is discipline.

Do not ask for HTML just because it looks nicer. Ask for HTML when the shape of the information matters: flows, dependencies, comparisons, timelines, interactions, diagrams, prototypes, or executive storytelling.

Do not use HTML as your source of truth unless you are prepared to maintain it.

Do not ignore token cost just because the output looks impressive.

And do not blame Markdown for every unreadable AI output. Sometimes the real problem is not the format. Sometimes the agent simply wrote too much.

Final Thought

Markdown is still the best language for durable technical knowledge.

HTML is becoming one of the best formats for rich AI generated artifacts.

The future of agent output is probably not one replacing the other. It is a layered workflow:

• Markdown, JSON, or YAML for truth.
• HTML for understanding.
• PDF, slides, or docs for distribution.

The best teams will not ask, “Should we use HTML or Markdown?”

They will ask:

Who needs to consume this, how will it be reviewed, and does it need to live beyond today?

Sources and Further Reading

This article was inspired by Thariq Shihipar’s recent exploration of HTML as a richer output format for Claude Code and AI agent workflows. His examples helped shape the central question behind this piece: when should agents produce simple, durable Markdown, and when should they generate something more visual, interactive, and closer to a small application?

The main reference for the debate is Thariq’s original collection, The unreasonable effectiveness of HTML, which shows several examples of self contained HTML artifacts generated for planning, reviewing code, explaining systems, creating diagrams, and building small interactive tools.

https://thariqs.github.io/html-effectiveness/

Simon Willison also published a useful summary of the discussion, adding context around why this idea resonated with developers experimenting with Claude Code and agent generated workflows.

https://simonwillison.net/2026/May/8/unreasonable-effectiveness-of-html/

To understand the community reaction, I also looked at discussions on Reddit and Hacker News. These threads were especially useful because they captured both sides of the debate: the excitement around richer artifacts, and the skepticism around token usage, maintainability, Git review, searchability, and security.

https://www.reddit.com/r/ClaudeCode/comments/1t8vni3/html_markdown_for_claude_code_outputs_thariqs/

https://www.reddit.com/r/codex/comments/1t8vv0y/if_your_markdown_plans_are_too_long_to_read_is/

https://news.ycombinator.com/item?id=48071940

For the token cost example, I used Anthropic’s public pricing page as a reference for Claude output token pricing.

https://platform.claude.com/docs/en/about-claude/pricing

To safeguard against this vulnerability, one effective measure is to avoid exposing the SSH protocol over the internet and utilize Azure Bastion Host. Azure Bastion, a fully managed PaaS service, enables secure connections to virtual machines via private IP addresses. It ensures secure and seamless RDP/SSH connectivity directly over TLS from the Azure portal or through the native SSH or RDP client on local computers. By connecting through Azure Bastion, virtual machines eliminate the need for a public IP address, agent, or specialized client software.

Azure Bastion protects all VMs within the provisioned virtual network, securing RDP and SSH connectivity without exposing ports to the external environment. Leveraging Azure Bastion enhances security by providing secure RDP/SSH access while isolating virtual machines from external threats.

It’s crucial to stay informed and maintain up-to-date systems to mitigate potential risks posed by vulnerabilities.

#CyberSecurity #OpenSSH #VulnerabilityManagement #Azure #BastionHost

• CVE - CVE-2024-6387
• About Azure Bastion