# Markdown for agents. HTML for humans. — Kogen

[Notes](https://kogen.dev/notes/)

# Markdown for agents. HTML for humans.

Almir Sarajčić · 14 September 2026

In May, Thariq wrote about the unreasonable effectiveness of HTML for Claude Code:

[!\[Thariq\](https://pbs.twimg.com/profile_images/1976939058741039104/r3GgzqRh_normal.jpg)](https://twitter.com/trq212/status/2052809885763747935)

[Thariq](https://twitter.com/trq212/status/2052809885763747935)

[@trq212](https://twitter.com/trq212/status/2052809885763747935)

·[Follow](https://twitter.com/intent/follow?screen_name=trq212)

[x.com/i/article/2052…](http://x.com/i/article/2052796100608974848)

[5:56 PM · May 8, 2026](https://twitter.com/trq212/status/2052809885763747935)

[17.9K](https://twitter.com/intent/like?tweet_id=2052809885763747935)
[Reply](https://twitter.com/intent/tweet?in_reply_to=2052809885763747935)

[Read 1.1K replies](https://twitter.com/trq212/status/2052809885763747935)

I wasn’t convinced. I quoted it the next day:

[!\[Almir Sarajčić\](https://pbs.twimg.com/profile_images/1861769506642604032/AYcB3yTk_normal.jpg)](https://twitter.com/ultrathinktrash/status/2053035151601352872)

[Almir Sarajčić](https://twitter.com/ultrathinktrash/status/2053035151601352872)

[@ultrathinktrash](https://twitter.com/ultrathinktrash/status/2053035151601352872)

·[Follow](https://twitter.com/intent/follow?screen_name=ultrathinktrash)

Unlimited usage must be nice. I’ll keep using Markdown with my limited Claude subscription. We solved this a long time ago: - Markdown exports to HTML - HTML works within Markdown

[!\[Thariq\](https://pbs.twimg.com/profile_images/1976939058741039104/r3GgzqRh_normal.jpg)](https://twitter.com/trq212/status/2052809885763747935)

Thariq

@trq212

x.com/i/article/2052…

[8:51 AM · May 9, 2026](https://twitter.com/ultrathinktrash/status/2053035151601352872)

[0](https://twitter.com/intent/like?tweet_id=2053035151601352872)
[Reply](https://twitter.com/intent/tweet?in_reply_to=2053035151601352872)

[Read more on X](https://twitter.com/ultrathinktrash/status/2053035151601352872)

To me, it looked like Thariq was either trying to sell us more of those Anthropic tokens or had gotten spoiled by unlimited usage. It just looked like a waste.

By August I’d reversed course:

[!\[Almir Sarajčić\](https://pbs.twimg.com/profile_images/1861769506642604032/AYcB3yTk_normal.jpg)](https://twitter.com/ultrathinktrash/status/2094401942801788979)

[Almir Sarajčić](https://twitter.com/ultrathinktrash/status/2094401942801788979)

[@ultrathinktrash](https://twitter.com/ultrathinktrash/status/2094401942801788979)

·[Follow](https://twitter.com/intent/follow?screen_name=ultrathinktrash)

Oh, how wrong I was about HTML vs Markdown for output. Now I tell Codex and Claude Code: no terminal output. Just give me HTML reports as artifacts/sites.

[!\[Image\](https://pbs.twimg.com/media/HRDOxPFXcAAAaBo?format=png&name=small)](https://twitter.com/ultrathinktrash/status/2094401942801788979)

[!\[Almir Sarajčić\](https://pbs.twimg.com/profile_images/1861769506642604032/AYcB3yTk_normal.jpg)](https://twitter.com/ultrathinktrash/status/2053035151601352872)

Almir Sarajčić

@ultrathinktrash

Unlimited usage must be nice. I’ll keep using Markdown with my limited Claude subscription. We solved this a long time ago: - Markdown exports to HTML - HTML works within Markdown

[12:28 PM · Aug 31, 2026](https://twitter.com/ultrathinktrash/status/2094401942801788979)

[5](https://twitter.com/intent/like?tweet_id=2094401942801788979)
[Reply](https://twitter.com/intent/tweet?in_reply_to=2094401942801788979)

[Read more on X](https://twitter.com/ultrathinktrash/status/2094401942801788979)

It’s September, years have passed in the AI era, and now I’m older and wiser. I think I’ve struck a balance between the two: agents write Markdown files that Astro then renders. They don’t continuously spend tokens writing all those repetitive HTML tags. They do that work once in the template, then later just write the content.

Of course, the nice-looking images and diagrams Thariq mentioned still need to be generated. The template only removes the repetitive presentation work.

The agent-facing layer is Markdown: cheap to generate, easy to diff, easy to edit by hand afterward. The human-facing layer is HTML: rendered by the template, not re-derived by an agent on every run. For these reports, HTML is the delivery format, not something I ask an agent to hand-author each time.

I still wouldn’t ask an agent to write raw HTML for a report it’s about to hand me. I’d ask it to write Markdown, and let a template already built for that job turn it into something worth reading.

[← All notes](https://kogen.dev/notes/)

---

Canonical page: https://kogen.dev/notes/2026-09-14/markdown-for-agents-html-for-humans