My concern here is that by gravitating to HTML you lose the ability for a human (you!) to easily co-author the document with the LLM. If it’s just an explainer for your consumption, that’s not a concern - but if it’s a spec sheet for something more complex, I deeply value being able to dive in and edit what is produced for me. With a HTML doc it is much harder to do that than with MD.
Now of course you could just reprompt your LLM to change the HTML - but when I already have a clear idea of what I want to say in my head, that’s just another roadblock in the way.
If this pattern becomes more common I suspect human/LLM co-creation will further dwindle in favour of just delegating voice, tone and content choice to the LLM. I was surprised not to see this concern in the blog post’s FAQ.
divbzero 7 minutes ago [-]
Yes, and you can always embed HTML in Markdown for <script>, <style>, <svg>, and other tags that cannot be coded in Markdown.
9dev 12 minutes ago [-]
I suppose that only applies if you constrain yourself to a raw teletypewriter emulator… in any proper coding environment, editing HTML should be absolutely simple - even an embedded WYSIWYG editor would be an option if rich model output is a way we head into.
Jakob 21 minutes ago [-]
We have been authoring HTML by hand for decades with ease. Text editors are very good at it, and many have commands to auto-wrap, auto-close etc. Reading and writing is simple.
4k0hz 22 minutes ago [-]
Is HTML really that much worse to edit than MD?
psychoslave 10 minutes ago [-]
Let’s see…
*No!*
I mean, <b>yes!</b>
It depends what we mean I guess, isn’t Markdown supposed to allow [hx]ml tags anyway if user need them? Then it’s more about asking the LLM to generate Markdown with this in consideration, and privilege rendering the output of reports in the preferred browser after relevant rendering.
bigfudge 40 minutes ago [-]
[dead]
steve_adams_86 7 minutes ago [-]
I was running into issues with markdown and mermaid the other day and decided to tell Claude to use HTML, then realized that opened up the option of JS as well. Given we were trying to model state management in an existing typescript application, we could use ts-morph to correctly map out the call sites within different components, even use math to determine various factors of refactoring or relocating and so on.
It ended up being a large document but it was infinitely more useful than plain old markdown. I think I’ll do it more often now. Creating interactive specs is a really fascinating way to work. I’ve always verified my work in similar ways, but this was more… Verification-forward, I guess. And it took hours instead of days.
It’s actually really fun to be building and refactoring these days. No idea how long the fun will last, but I’m thoroughly enjoying it right now. I know it will make some people think I’m a hack, but I know that approach enabled me to do a faster, more targeted, ultimately better job of improving state management in the application. It’s not because Claude wrote the code (I still did quite a bit of it), but because Claude helped me establish the right work to do for the right reasons, using tools I couldn’t dream of throwing together 5 years ago.
forgotusername6 4 minutes ago [-]
I've been struggling with markdown recently as I really want the claims it makes in documents to be programmatically verifiable e.g. citations, I want a simple script to check that each of the files and lines of code it references actually exist. Perhaps HTML can be used for this. It certainly has a better chance than markdown.
momojo 1 hours ago [-]
When exploring a new idea or tool, my go to prompt is
```
In a single index.html, no dependencies, sparse styling, create an app that <idea>
```
Even before AI, it's how I built small tools, and there's something lovely about being able to email my friends the tool, and tell them "If you want to make a change, toss it to your LLM!"
l3x4ur1n 39 minutes ago [-]
Same. When I iterate on a design for a new client, I create a simple index.html with inline CSS and when I'm satisfied with the result I take the file and insert it next to my project template files and just ask the LLM to take the design from index.html and work it in the template files.
drob518 1 hours ago [-]
I never really thought about this use case before, and I feel a bit dumb because of that. It’s so obvious that it would be useful. My focus with LLMs so far has been on The App, not all the ancillary stuff around The App. All that ancillary stuff doesn’t have to be fully complete or polished and doesn’t have to handle every possible case. It just needs to be functional enough to be useful. When you’re done with it, throw it away and generate a new one tomorrow.
readitalready 11 minutes ago [-]
I moved from Markdown to JSON for all spec writing about 9 months ago. Although not HTML, it still has the same benefits. Claude and the other models are just so much more reliable in a structured format like JSON/HTML/XML.
The most important thing is that I can run static analysis on a structured format. This is important even for my spec documents. I can write data fields and have static analysis analyze it. For example, to confirm database fields match across various spec documents, etc.. The static analysis is also why you use JSON/XML instead of HTML, since you can now have your own custom schema.
Also don't use YAML, as that's far more unreliable. (If you chop a YAML file in half, it's still valid)
apsurd 2 hours ago [-]
Web technologies got so many things right. People complain about it so much but it's amazing.
I worked with a vibe coded app at my last job (and since quit due to it) and because it was a nextjs SPA frontend with a separate API backend, the user facing urls didn't match the backend endpoints. Because AI uses react hooks for everything, state is in-memory, url-based routing isn't a thing unless you design for it. So links aren't free and thus we have no way for users to link to anything other than top-level entry points. LINKS! Especially for internal tools, everything being linkable is vital to collaboration and problem solving.
The need for uniform resource locations and verbs was so well thought out, 30 or 40 some odd years ago.
alsetmusic 1 hours ago [-]
> I’ve started preferring HTML as an output format instead of Markdown and increasingly see this being used by others on the Claude Code team, this is why.
This is why I read long agent output either by using VIM and MacOS Quicklook (with a markdown extension for rendering) or paste output into MarkEdit (an editor with a preview pane; I think it’s cross platform?). Worst case, have an agent build you a simple local web page that interprets Markdown and renders it. Markdown was invented as a shorthand for web syntax[0]. That’s what it’s for! I bet you spend more tokens and time asking an agent to convert its native markdown to html than any of these.
If you want to be vibe all the way, why don't you ask a bot to summarize the long output?
Using bots has been insane and self-referrential.
ryandsilva 42 minutes ago [-]
A couple of tradeoffs I don't see mentioned here for HTML vs MD:
- HTML is significantly less token-efficient
- Difficult to provide precise feedback on plans HTML, much easier to do this in MD.
Both of these tradeoffs set Anthropic up for success. Using HTML as our medium will increase token usage, and I'd bet they're investing in tools to mark up HTML (part of Claude Design) which will help improve lock-in. Either coincidence or brilliant strategy.
doc_ick 15 minutes ago [-]
~html has more capabilities than markdown~ the real title
Weren’t llms specifically originally set to output and print markdown format since it is simpler and easier everyone to read? No different rendering/libraries/apis to worry about…
htch 43 minutes ago [-]
We’ve been doing this for a couple of months at work for internal memos and decision records, it’s really powerful. I love being able to drop in interactive visuals and more dynamic content. We have a Cloudflare R2-backed Document Store for managing them, and CLI for publishing, and I’m working on an MCP server for long-term discovery and context.
My team kept asking if they could leave comments though, so I built Annotent [1] to help with that, which is also MCP-backed.
I'm thinking of adding support for GitHub-flavored markdown (including things like Mermaid diagrams) in my agent wrapper tool and then adding something like a skill for Claude Code to always write GitHub-flavored markdown and use its features when communicating with me. Seems a lot better than general Markdown.
Though now I'm wondering: why not just add full HTML embedding support as well? I'm talking not just for specific deliverables, but for any of the agent's responses with the user.
ocimbote 34 minutes ago [-]
Have we gone full circle? From the invention of HTML to the rebirth of plain text with MD to the rediscovery of HTML anbrhe age of LLM?
The facts that this article needs to list the pros of HTML over MD, like inreraction, visual density, etc, is weird to me. Maybe the ahdience is not tech-savvy people but I read it as an unnecessary word salad.
ozim 20 minutes ago [-]
I don’t think so.
It is just realization by author that HTML is also useful tool and MD lacks some stuff.
He didn’t write anything about “now we should stop using MD files”.
It is more like: “I see I can do cool stuff with HTML and found cases where it definitely is right tool for the job”.
k4rli 16 minutes ago [-]
It feels like a word salad that's been created to hit a word target because it's also LLM generated. Really not worth spending 5-10 minutes reading some "AI" output.
jaaron 1 hours ago [-]
For similar reasons, I strongly prefer org-mode to markdown. I find that with org-mode and extensions (such as in-line elisp) I have a _significantly_ more powerful system. For example, specs can have tasks and roadmaps inline which reduces risk of drift. The biggest downside is, unfortunately, not enough folks are emacs proficient.
I hadn't considered HTML and I'm definitely going to try this.
I’ve also realized CC is exceptional on html, creating local apps for reviewing output, dashboards sourced from DuckDB, etc.
To review PRs in a little custom app is a very good idea. Who cares about 1.2x more tokens when clarity is squared?
Nice article!
BretonForearm 2 hours ago [-]
Many of us had CC routinely generate HTML ever since it became available. Surprised that it's presented as some kind of novelty.
drob518 56 minutes ago [-]
I don’t think the idea of generating HTML is a novelty. Anyone using an LLM to create a web app has done that. Any “novelty” here is the idea of favoring HTML rather than Markdown for internal docs like specs, design docs, etc. Maybe you were already doing that. I sure haven’t been. In hindsight it’s obvious that it would be useful in some circumstances. Previously, I’ve had a bias against HTML because it’s annoying to read in a text editor.
jdw64 2 hours ago [-]
So the argument seems to be that HTML is stronger than Markdown for disposable UI, visualization, and interactive artifacts. It also works well as an external memory object because it can be linked to and opened directly.
For visualization and animation, I do think HTML can be a very good format.
If LLMs become part of the workflow, this can definitely be useful. But on the other hand, maintaining HTML itself is more annoying than it first appears.
I do something somewhat similar. I download good CodePen examples and store them in a GitHub library so I can reuse them later. It works, but version management becomes quite difficult in practice. So I think there are real tradeoffs.
kulikalov 2 hours ago [-]
Md and plotly is all you need. The only thing that is truly missing is some sort of Markdown-based forms
postalcoder 1 hours ago [-]
Yeah, I agree with this. I've been doing the same thing. Whenever I have to do a review, I ask the llm to create a dashboard. It's a godsend for reducing cognitive burden.
I think the reason stuff like this wasn't done earlier was due to fears about context pollution, but post training has gotten so good that you can do virtually anything in the context window and not have it affect the quality of output.
I’ve been prompting my way to all kinds of interactive HTML artifacts the last month or so. It’s way more fun than making decks and static documentation.
I even did a workshop with PartyKit cursors, dot voting, reflection comments, and an individual rating at the end.
Oh, and I can add super lightweight analytics so I know who actually reads my things or interacts with my prototypes. ^_^
estetlinus 37 minutes ago [-]
Blog post plz
gabesullice 2 hours ago [-]
It's been confusing to me that so many people have treated markdown as the lingua franca for agent instructions when their training corpus must be dramatically biased to HTML instead of Mardown.
Markdown only makes sense for us meatbags becuse it's easy for us to edit and version control, but if you're sharing anything where the audience is an agent publicly, HTML must be just as interpretable.
Kwpolska 1 hours ago [-]
I guess the author has never heard of Markdown editors with a preview feature, and doesn't know that the Claude Code VS Code plugin opens plans in preview mode.
weird-eye-issue 59 minutes ago [-]
Are you just trying to pretend that Markdown is as rich as HTML and that all the use cases that they described are possible with Markdown?
jason1cho 40 minutes ago [-]
Markdown was a hype in late 2010s that has cooled down due to chatbots.
In turn, chatbots pump up markdown by making it the default output format.
k4rli 18 minutes ago [-]
I've felt the opposite. With MD being the preferred planning+documentation output for LLMs, the time of "hype" seems to be now. It seemed just a few years ago that devs hated writing properly formatted markdown.
whatever1 1 hours ago [-]
Do we have local first html renderers that don’t complain about cors and wrong file addresses? I don’t want to spin up a server just to open an HTML file
imbnwa 29 minutes ago [-]
Feels like markdown is token-efficient since its abbreviating HTML tags. Think about a large table. Also, HTML can't be especially rendered inside, say, Neovim, so now interacting with an LLM interface gravitates towards GUIs. Good for accessibility, I guess, there's that. Maybe the need for token efficiency will finally realize my dream of writing Slim[0], or some such, straight to the browser, full native compat.
Now of course you could just reprompt your LLM to change the HTML - but when I already have a clear idea of what I want to say in my head, that’s just another roadblock in the way.
If this pattern becomes more common I suspect human/LLM co-creation will further dwindle in favour of just delegating voice, tone and content choice to the LLM. I was surprised not to see this concern in the blog post’s FAQ.
It ended up being a large document but it was infinitely more useful than plain old markdown. I think I’ll do it more often now. Creating interactive specs is a really fascinating way to work. I’ve always verified my work in similar ways, but this was more… Verification-forward, I guess. And it took hours instead of days.
It’s actually really fun to be building and refactoring these days. No idea how long the fun will last, but I’m thoroughly enjoying it right now. I know it will make some people think I’m a hack, but I know that approach enabled me to do a faster, more targeted, ultimately better job of improving state management in the application. It’s not because Claude wrote the code (I still did quite a bit of it), but because Claude helped me establish the right work to do for the right reasons, using tools I couldn’t dream of throwing together 5 years ago.
``` In a single index.html, no dependencies, sparse styling, create an app that <idea> ```
Even before AI, it's how I built small tools, and there's something lovely about being able to email my friends the tool, and tell them "If you want to make a change, toss it to your LLM!"
The most important thing is that I can run static analysis on a structured format. This is important even for my spec documents. I can write data fields and have static analysis analyze it. For example, to confirm database fields match across various spec documents, etc.. The static analysis is also why you use JSON/XML instead of HTML, since you can now have your own custom schema.
Also don't use YAML, as that's far more unreliable. (If you chop a YAML file in half, it's still valid)
I worked with a vibe coded app at my last job (and since quit due to it) and because it was a nextjs SPA frontend with a separate API backend, the user facing urls didn't match the backend endpoints. Because AI uses react hooks for everything, state is in-memory, url-based routing isn't a thing unless you design for it. So links aren't free and thus we have no way for users to link to anything other than top-level entry points. LINKS! Especially for internal tools, everything being linkable is vital to collaboration and problem solving.
The need for uniform resource locations and verbs was so well thought out, 30 or 40 some odd years ago.
This is why I read long agent output either by using VIM and MacOS Quicklook (with a markdown extension for rendering) or paste output into MarkEdit (an editor with a preview pane; I think it’s cross platform?). Worst case, have an agent build you a simple local web page that interprets Markdown and renders it. Markdown was invented as a shorthand for web syntax[0]. That’s what it’s for! I bet you spend more tokens and time asking an agent to convert its native markdown to html than any of these.
0. https://daringfireball.net/projects/markdown/
Using bots has been insane and self-referrential.
Both of these tradeoffs set Anthropic up for success. Using HTML as our medium will increase token usage, and I'd bet they're investing in tools to mark up HTML (part of Claude Design) which will help improve lock-in. Either coincidence or brilliant strategy.
Weren’t llms specifically originally set to output and print markdown format since it is simpler and easier everyone to read? No different rendering/libraries/apis to worry about…
My team kept asking if they could leave comments though, so I built Annotent [1] to help with that, which is also MCP-backed.
1. https://www.annotent.com/
Though now I'm wondering: why not just add full HTML embedding support as well? I'm talking not just for specific deliverables, but for any of the agent's responses with the user.
The facts that this article needs to list the pros of HTML over MD, like inreraction, visual density, etc, is weird to me. Maybe the ahdience is not tech-savvy people but I read it as an unnecessary word salad.
It is just realization by author that HTML is also useful tool and MD lacks some stuff.
He didn’t write anything about “now we should stop using MD files”.
It is more like: “I see I can do cool stuff with HTML and found cases where it definitely is right tool for the job”.
I hadn't considered HTML and I'm definitely going to try this.
To review PRs in a little custom app is a very good idea. Who cares about 1.2x more tokens when clarity is squared?
Nice article!
For visualization and animation, I do think HTML can be a very good format.
If LLMs become part of the workflow, this can definitely be useful. But on the other hand, maintaining HTML itself is more annoying than it first appears.
I do something somewhat similar. I download good CodePen examples and store them in a GitHub library so I can reuse them later. It works, but version management becomes quite difficult in practice. So I think there are real tradeoffs.
I think the reason stuff like this wasn't done earlier was due to fears about context pollution, but post training has gotten so good that you can do virtually anything in the context window and not have it affect the quality of output.
I even did a workshop with PartyKit cursors, dot voting, reflection comments, and an individual rating at the end.
Oh, and I can add super lightweight analytics so I know who actually reads my things or interacts with my prototypes. ^_^
Markdown only makes sense for us meatbags becuse it's easy for us to edit and version control, but if you're sharing anything where the audience is an agent publicly, HTML must be just as interpretable.
In turn, chatbots pump up markdown by making it the default output format.
[0]https://slim-template.github.io/