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.
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.
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.
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.
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…
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."
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.
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)
The real change is in generation side, and now the spec docs are LLM generated JSON based on other spec docs or human prompts. LLMs seem to write JSON better than Markdown or YAML, if you tell it to follow a schema.
Visual explainers certainly come in hand. You need to have both the extra time and cost of tokens accounted for when you ask for these. As well as maintainability - you lose things like vcs/diffs over plans that are much more readable as markdown.
The more interactivity on the surface, the better. Esp if they create feedback loops with the agent. Simple annotations to start.
Markdown still goes a long way. I’ve effectively been enriching plan rendering in Plannotator. Now supporting GFM, custom svgs, etc.
https://github.com/backnotprop/plannotator
For fun, I also enabled annotations on top of these type of svgs, see here https://x.com/plannotator/status/2052851731998941380?s=46
I run a web server on my Mac. Consequently, I have an HTTP process available. I keep intending to make an endpoint that Claude can use. I would tell it to make a document for commenting (or put a list of options or whatever) and post it to, I guess, the planning folder we are working in. The endpoint would know how to do this because I wrote it.
When it gets there, I would, I wanted to keep it, tell Claude to integrate the results into the file as static HTML. Or, if I don't care about that, just read it and do whatever I said and leave it disconnected.. The goal isn't to make a website.
This supports interactive conversations with Claude via HTML.
The endpoint verifies that the destination specified by the POST is in my project folder. If it points at an existing file, it creates a version. It does not overwrite.
I added a CLI, watchFile, that blocks Claude until the file shows up.
And made a skill that tells Claude to respond nicely to "Make an interactive document that...".
Claude Code has basically made software functionality, "Your wishes come true".
Now I have a favorite in my bookmark bar for each project I am working on that shows me the docs.
I'm so happy.
2. It is not designed to work as a single file, and AFAIK there is no universal way to do it.
3. its not as easily editable as Word or Excel to most people.
4. There are alternatives such as PDF.
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.
> 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.
- 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.
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.
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.
I'd still want the LLM using markdown, its a much better fit than HTML for loading context. I'd want to consume it in a nicer visual representation. It writes something like `<ds-table>` and it builds to a styled HTML table for me.
Surely a html page could do the same but I would see that as the last step, to give to someone else.
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.
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.
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.
Wondering if you are referring to adherence to required data in a schema when you say LLMs do better with json vs markdown, or something else? Or perhaps to tool calls and/or strict json output being more reliably formatted for clean extraction?
Classical overly confident llm bullshitting.
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.
Using Claude Code: The Unreasonable Effectiveness of HTML
If that's the goal, use haml and sass
You get human readability + the power of html
It's a very beautiful language, it's quite simple, if you like simple.
Generating markdown is faster so unlike our friend here, I still do use it for straightforward things.
BUT, in general, I tell Claude, "I think we should starting a project planning folder for this. Put (the stuff we just talked about) into an html doc. while you're at it, make an index.html and put relative link to the page with a little explanation of what we are up to."
Or, just yesterday Claude and I worked out the design for a substantial AI enabled database tool. I had it make an explanatory doc for my team. It was a single html file that navigated through forty scenes that demonstrated it. MAGIC.
If you aren't doing your collaboration with Claude in html, listen to this guy. Your life and work will be better.
If you rename a .html file to .md, your markdown viewer should render it just the same as your browser did.
In turn, chatbots pump up markdown by making it the default output format.
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.
"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 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.
What in the world.
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.
Currently working on a dumb little mobile game with isometric view and sound:
- told codex to write a tool that lets its place blocks in a prepared three.js document and have chromium dev tools take a screenshot. It made up a little JSON structure that defines blocks / colors and some other effects and it outputs 2.5d tilesets.
- told it to create a uv python script that would let it define sounds and music, and it made a yaml format that lets it create noises.
We completely shot past the svg pelican test. Codex has created both perfectly adequate prototype art of soldiers/knights/priests as well as a prototype soundtrack.
No, we've been generating it with templates or authoring templates.
Authoring HTML by hand is a very early 2000s thing to do.
HTML made by Claude will, by default, be "sleek, modern", with colorful tables, cards, maybe Tailwind for styling. And, of course it will, if you wanted a barebones HTML, you would just have asked for markdown!
So the LLM decided to present some content using 4 cards, and you now want to add new itens. You can't just add new lines of text: you need to copy the whole HTML of the cards. But the LLM used different colors for each card, so now you have the first cards with varying colors and the new cards all the same color as the last card. Now you have to think about colors... etc etc
*No!*
I mean, <b>yes!</b>
It's arguable even more readable.
<b>bold</b> <i>italic</i> <u>underline</u>
I can never remember how many stars and ticks correspond to what in markdown.
1: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/...
2: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/...
3: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/...
overall i'm seeing a potential here for more human authoring, as you can really multiply the surface of your inputs with deterministic widgets rather than just delegating.
BUT, I only do this as an easy way of referencing specific ideas and text in notes to instruct Claude. I say, "I have added notes. Read them and adjust the doc accordingly." Or, "Read the notes I added. Turn them into html."
It's an insanely productive pattern.
It's usually faster though, so you get to spend more time on thinking.
I’ve done something similar with Figma-like commenting and find myself pulling it into all kinds of personal projects.
I think most of us live somewhere in the middle, using the right tool / output for the job.
The same could be said of any proprietary file format (which HTML is not!) Designers aren't concerned when they create inside a .psd or .ai file.
This feels very similar IMO.
I know that it's 2026 and we've spent the last 15 years hiring people into our field who don't understand the hacker mindset but I didn't think that I'd find them here. They would have been ran out pretty quickly.
On a serious note some kind of rich Markdown would definitely help.
``` 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 guess it’s both
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.
I bet that LLMs will actually help generate real links going forward.
What i learned, by fire, is that nextjs works well with its nested routing and layout-to-hold-context magic. it's quite nifty but it's not free and not obvious, you have to design for it. I can't state enough that AI will ship a billion hooks, it loves hooks for self-contained state. My colleague made a good point that that style is a feature; it limits blast radius of N features all building on top of each other.
Yeah i had to move on from there.
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.
What’s harder than with markdown about precise feedback? You can have ids, sections and more with tags.
But, on the other hand. That could be a trade worth taking. Co-working with claude to create a pretty big plan for a rewrite (i know, i know), and showing it to the team is a lot easier in HTML compared to md.
For me, this is just another tool in the toolbox. Doesn't need to be black and white. html or md. Can be both.
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 hadn't considered HTML and I'm definitely going to try this.
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.
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.
Using bots has been insane and self-referrential.
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. ^_^
You don't have to host html files. You can just email it and any browser can view it.
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.
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)
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.
Is it really unreasonably effective?
While it has been used in the context of HTML before, it's a bit of a "meme" as several papers used that phrase. Much like the "X is all you need" snowclone.
The HTML version dates from 2021 (https://shkspr.mobi/blog/2021/01/the-unreasonable-effectiven...) when client side rendering and web apps were still their peak.
I also love how maybe 10% of the posts on here are like "some thing that has existed for 40+ years ,/:/; Claude/chatgpt". So much advertising at the expense of a dead internet it's ridiculous.
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'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.
I tend to not actually read more than 100-lines of anything anymore. I've long referred to myself as "the Google generation": only being able to read the summaries in a search result. That, and the typical doomscrolling model of social media have affected my attention span. Reading anything more substantial takes real effort now.
Presumably you mean rendered HTML rather than the source documents?
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 is incredible how far you get with a single HTML-file, containing styles and JS, when building dashboards, small apps and other utilities that can interact with an API or otherwise fetch data from somwhere.
I just drop it on my personal ~ folder on the shared server at work and voilà, everyone can check it out and use it immediately!
its super convenient to be able to throw tools like this together and load them on a static site.
I absolutely hate the absolute rot these tools have caused to people’s brains.
Else I fully expect to get saddled with turning a temporary thing for a very narrow problem into something production ready.
We fired him.
He’s suing for wrongful termination and…homophobia.
People are completely cooked. These tools are too powerful and normies are too stupid to use them responsibily.
2. One of the limiting factors of LLM is context. An html table takes up way more tokens than a markdown table. Especially if it's a WYSIWYG editor that has all kinds of css and <span> tags just for fun.
That might be the case today but there’s no reason for it to always be true. They are different representations of the same thing, an LLM could (arguably should!) store an internal representation that uses fewer tokens.
Even after React became popular, people are still manually typing out HTML elements, although they call it "JSX" instead, but in reality it's just HTML.
My first blog on the internet literally was a bunch of .html files, where my post "template" was the first post copy-pasted when you wanted to make a new post. Changing the design involved changing the same thing across all files.
Typing out <p> for every paragraph is annoying, for sure. But a converter that switches out \r\n\r\n for a new paragraph would be a reasonable middle ground IMO.
Also I often call out my colleagues if they try to put a table in markdown. Markdown is not built for tabular data in most professional settings (i.e., one or two table cell could easily take a whole line of markdown to express). A basic <table><tr><td style="background: red">some number</td></tr></table> goes a long way.
Both. We manually run HTML just fine back in the day.
Yesterday. Astro components.
3 million people will have seen it as I type this. More next week.
You add “include” tags to your HTML file and your web server like nginx or varnish would replace it with the fragment at runtime.
<!--#include virtual="../footer.html" -->
Very cheap, stable, and very big changes across the whole website could be done instantly since cache invalidation is trivial (the web server knows all modified dates of all fragments).
Also, no additional CDN or caching needed. Later, with CDNs there was even a variant where these fragments were hosted at the edge (ESI).
To me it feels like a worse experience, and they probably feel it too, but it makes sense from an optimization perspective. I've probably learned some shell tricks, but also going blind from watching Claude try dozens of variations of some multi-line chained and piped wall of bash nightmare, instead of just reading a few files.
Also: https://platform.claude.com/docs/en/agents-and-tools/tool-us...
It also gives tips on reducing context size when you run /context .
Presumably they are actually starting to feel the pinch on inference costs themselves with what still feels like a fairly generous max plan.
I did not go to a front end high school.
Most frontend devs have no idea what any of that means. But then it seems everyone who can write 3 lines of code professionally refers to themselves as an ”engineer”.
CSS, on the other hand...
I'm not and I've used it for years. With Markdown being a thing that has been less common, sure, but that's more of a zeitgeist thing.
Nope, it's a fixed, coded and shipped UI: the agent TUI.
I'd definitely call that on-demand, purpose-generated ephemeral UI.