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.
``` 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!"
Arguing for html on a platform with less rich semantics than markdown is just ultimately funny
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.
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.
For the most parts you just write the regular Markdown headers and paragraphs, embed images, insert tables etc without the need for any HTML tags, making it readable in source form. And if you want to embed an SVG file for example, which the author of the article mentions as one use case, you just embed the SVG directly, and people can render the Markdown in their favorite viewer.
Let's say you're viewing a raw Markdown file in VS Code. You come onto an HTML tag, so you hit Cmd+Shift+V to open the preview and that's it.
Of course for full-fledged web pages with interactive buttons and fully customized styling and all of that, which the author shows in some examples, this is not feasible. But you can get very far when you have mostly text/images/tables and just want to add some extras here and there.
[1] https://daringfireball.net/projects/markdown/syntax#html
I talk to laypeople about their AI work -- I am constantly doing this, inserting myself into AI conversations on the street like an anthropologist when I encounter them...
HTML artifacts are the new browser URL bar, wherein some users have a mental model that that bar is actually Google.
Many people now talk about their "spreadsheet" or their "presentation" or "marketing tear sheet", or "slide show", "competitive analysis", "hvac system diagram" or whatever the thing they were working on and how lame it was working with ChatGPT or Claude Web.... and how miraculous Claude Code or OpenClaw is with creating these new documents...
I will ask them what the documents actually are and what the difference in experience was. It takes a lot of teasing (because they don't have the computing vocabulary yet) or having them show me, and it will always come down to that the artifact is HTML.
Their pleasant experience is that it is iterating on an HTML file (+CSS +images) living on a filesystem with high quality instant rendering; plus it can sprinkle JavaScript when it needs to. It might even revision control it without them knowing if there's a git system. [I suggest they checkpoint their work if they don't; revision control is the next stage of learning for the laypeople?]
Whereas the Web-embedded experiences are stabbing multiple times on a DOCX/PPTX/XLSX lingering in a context window and a vague notion of local storage (rendered as HTML anyway in a sidebar), etc. The HTML workflow also allows other media to be integrated much more easily.
So really all this presentation work is Vibe-Coding by the masses; they don't need to know about all the turtles underneath them. But if they are willing, they could crack it open and see and edit it; or easily hand it off to another agent.
Go figure that the system created for collaborative multimedia communication ends up being useful for the machine intelligence to help us communicate.
I hadn't considered HTML and I'm definitely going to try this.
For example, user says "build a report with revenue and orders by month and show 100 most recent orders". The agent would write a spec that would get rendered by our frontend.
This runs fast, but we were drowning in feature requests for what the framework could render (e.g. "I don't want labels here", "I DO want labels there", "can this chart be a heatmap", etc.)
A few months ago, we let the agent just write HTML instead. It takes longer to generate, but you get unlimited customization.
There are a host of issues with the new approach (non-technical users debugging a monstrous app they created), but net-net our customers like it much better.
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.
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)
You don't have to host html files. You can just email it and any browser can view it.
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. ^_^
Is it really unreasonably effective?
I have been building a slightly different solution to the same problem. So far I’m pretty happy with the results and I have enough returning users that I think others are too (https://sdocs.dev/analytics).
I’ve built SmallDocs (https://sdocs.dev; Show HN: https://news.ycombinator.com/item?id=47777633).
SDocs is cli (`sdoc file.md`) -> instantly rendered Markdown file in the browser
When you install the cli it gives you the option to add a note in your base agent file (`~/.claude/CLAUDE.md`, etc.). This means every agent chat knows about SDocs and you can say “sdoc me the plan when you’re done with it” and the file will pop open instead of you having to find that terminal session to know it’s done.
Going browser first means you’re not required to install anything to get a great experience.
Despite being in the browser, the content of SDocs rendered Markdown files remain entirely local to you. SDoc urls contain your markdown document's content in compressed base64 in the url fragment (the bit after the `#`):
https://sdocs.dev/#md=GzcFAMT...(this is the contents of your document)...
The url fragment is never sent to the server (see https://developer.mozilla.org/en-US/docs/Web/URI/Reference/F...: "The fragment is not sent to the server when the URI is requested; it is processed by the client").
The sdocs.dev webapp is purely a client side decoding and rendering engine for the content stored in the url fragment.
This also means you can share your .md files privately by sharing the url.
To go a bit deeper towards the HTML side of things I’ve added tagged code blocks that the agent is given documentation on how to use. Eg ```chart or ```mermaid (for mermaid diagrams). These then become interactive elements on the page (mermaid is best example of this currently)
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.
I'm also not convinced that it solves meaningful problems :
> I've found I tend to not actually read more than a 100-line markdown file, and I certainly am not able to get anyone else in my organization to read it. But HTML documents are much easier to read, In my experience, LLMs are not concise when it comes to documentation, so using an easier file format to read because the text is too large sounds to me like solving the wrong problem
> Markdown files are fairly hard to share since most browsers do not render them natively well. Yes, but developers tools (IDE, Git forge) do. What most/some of them don't render natively IS HTML.
What I don't like is that all the resulting pages look the same. It's so easy to tell when a page is authored by Claude, and by now, I get the same “ugh another one” feeling as Dall-E generated images would give when they were completely overdone.
Maybe it's just be, but if not, maybe HTML generated outputs will also end up being dialed down from where they're at now.
But maybe not, since it's obviously a useful thing to be able to do. I wonder if there's a way out. To be able to introduce some natural entropy so not everything ends up looking the same. I guess not, since we're using machines whose natural mode of behavior is regression toward the mean. And maybe having it be harder to tell the author wouldn't even be desirable anyway.
Markdown is a lightweight document format that leans toward easy writing, reading, and sharing. It is much simpler than HTML, easier to edit by hand, and works well for notes, documentation, drafts, README files, and content that may later be converted into HTML, PDF, or other formats.
That's why I'll continue to use Markdown for most of my notes and documentation, while I'll only use HTML for "public facing" documents.
I don't have any issue with markdown though - but terminal isn't a place to review it and leave useful feedback. Use one of the many tools that are popping up or build your own (like I did) to leave comments and iterate.
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.
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.
Markdown remains great because the other side is just going to use Claude to do their work anyway, and I can use Claude to verify their work meets my specifications.
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!
My team kept asking if they could leave comments though, so I built Annotent [1] to help with that, which is also MCP-backed.
Apologies if I'm slightly demeaning here, but what? Markdown is largely plaintext. Unless the output is completely littered with markdown formatting (specifically, imo, tables and maybe links would be the hardest for a human to parse), is this not just saying "I have a difficult time reading large bodies of text" (which is of course fine - people prefer different ways ingesting information)
From reading the post, this seems like a "I personally prefer more visual, interactive elements in output" rather than "agents using markdown leads for less understandable output", and not at all what I would recommend for the average person to use unless said agent or interface or whatever had an extremely seamless way of displaying the HTML. If I had to open the agents response in a browser every time I wanted anything detailed I would lose my mind.
I've certainly had agents generate more rich visualizations such as through html, but I can't imagine using that as my default.
Surely a html page could do the same but I would see that as the last step, to give to someone else.
- work text / human or mixed input: markdown, plain text
- fancy looks / interaction: html
avoid creating problems, try solving them instead. and don't start futile smoke campaigns.
What happens when my site changes style, I put it back through the LLM I guess and get some bonus hallucinated content.
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.
These days, modern LLMs just get it right first time. I like these little tools for myself. E.g. some are like this one here: https://viz.roshangeorge.dev/voxtral-viewer/?t=jeffrey-epste...
Which I use for things like reading podcasts (I’m not much of a listener - prefer to read) all single page HTML. I also make little sims for myself like: https://viz.roshangeorge.dev/baby-opportunity-cost/
The single page format has some conveniences like you can iframe it in when you want like I do on this blog post to illustrate an idea: https://wiki.roshangeorge.dev/w/Blog/2025-02-14/Fertility_Ra...
LLMs are good at tag demarcation. I wonder if that’s why we use tags for in-band signaling (<reasoning>) etc. or whether they’re good for it because they trained them to be good for in-band signaling. Would be cool to hear from someone at a lab about this.
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 html I don’t like the extra ornaments (borders, bullets, badges, etc).
To be fair, I usually ask for concise and specific information, where this kind of response style would be a distraction.
Sure enough, this is full of listicles and of a length no human would write for an idea as simple as "Use HTML instead of Markdown."
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…
Classical overly confident llm bullshitting.
Using Claude Code: The Unreasonable Effectiveness of HTML
This is the sort of observation that should make you concerned about your own skills, rather than spur you to generate an article (longer than you can read easily) trying to give advice to other people.
The linked article could have been made using Markdown, and yet the author still chose to represent themselves this way; there's no point changing the tool when the problem is the user.
"HTML can convey much richer information compared to markdown. It can of course do simple document structure like headers and formatting, but it can also represent all sorts of other information"
Yes exactly, and markdown is used when someone wants to just have raw text.
If that's the goal, use haml and sass
You get human readability + the power of html
Because it can have little components with jsx (html like) bits, it’s fairly human readable and editable.
Components give it semantic compression and the high level scan makes it easier to understand and change.
> Tabular data using tables yes > Illustrations with SVG yes > Code snippets with script tags yes > Workflows using SVG and HTML svgs yes > Images using image tags yes > Design data with CSS no > Interactions using HTML elements with javascript + CSS no > Spatial data using absolute positions and canvases no, although svgs help
That said, I can kinda get behind this ‘html, not markdown’ idea - as much as I like keeping things lean and mean, and markdown is ‘just enough’ semantics and style on top of plaintext… it can admittedly be more useful to recieve a more flavorful writeup from an LLM, if it’s going to be a piece that really requires you to engage with it, rather than just a quick read. Certainly a better fit for reports.
It's the best markdown editor.
So when I need to check any past reference I just open my folder or files.
Html it's so ugly.
I wish IA products add a save al chat button, to avoid copy and paste every response.
I don't know, maybe, you could just pay people to use it, and see where the problems are, and then be informed by that?
We're using LLMs as if human contact and experience is hard to come by at a point in history when it's anything but. These goofy models are a complete and total dead end. They're actively in the way of better approaches.
If can use emojis in my terminal text editor - even in a Markdown document itself - why the hell can't I bold or italicize?? We desperately need to fix this insanity.
Markdown by itself is: Headings, bold, italic, lists, blockquote, code, horizontal rule, link and image. That's it. Everything else is some sort of custom addition like tables.
Surely in 2026 we can figure out how to make this a universal standard.
I truly despise Markdown. I'd say about 25% of my posts on HN is me ranting about how much I hate it. This has mostly just lowered my karma, but that's OK. I'm not wrong, it sucks.
