If you spend any time in AI developer communities, you encountered the HTML vs Markdown debate this year. It ran long, got heated, and produced more opinion than evidence. But a practical consensus has emerged, and it is actually quite clean.

The argument in brief

The pro-Markdown camp: models trained on vast amounts of Markdown are optimised to produce and consume it. It is compact, human-readable, and semantically simple. Using it keeps content close to what the model natively understands.

The pro-HTML camp: HTML is semantically richer, universally understood by browsers and rendering engines, and gives you explicit control over presentation. It is the actual standard for web content.

Both camps were mostly right. The mistake was framing it as a choice.

Where each belongs

The consensus that has settled in practice:

Markdown is for anything system-close.

Instructions to agents. System prompts. Memory files. Configuration for AI tools. Anything that lives close to the model, gets passed through context windows, or is consumed by an automated process. Markdown is compact, it parses well, models have excellent intuitions about its structure, and it keeps token counts manageable.

HTML is the presentation layer.

Once content needs to be rendered for a human audience — on a website, in an email, in a document — HTML is the right format. It gives you semantic control, accessibility hooks, and precise rendering behaviour that Markdown simply cannot match. Trying to do presentation work in Markdown is working against the grain.

The practical takeaway

Design your AI systems with this split in mind:

  • System prompts, agent instructions, skill definitions, memory: Markdown
  • Rendered output for humans, website content, emails: HTML (generated from Markdown or directly)

The pipeline often looks like: model works in Markdown → output gets rendered to HTML at the presentation layer. This is how most mature AI-integrated publishing systems are now built, and it is the correct pattern.

The debate was not about which format is better. It was about a missing architecture decision that most people had not made explicitly.

Thoughts on this? I am particularly interested in how organisations are handling this split in enterprise AI deployments. Get in touch.