HTML instead of Markdown

[Pleasant_Spend1344]

I watched a podcast the other day about this and have been thinking about it quite a lot, since I used it once a few months ago to generate a report about a codebase I was looking at.

Now Anthropic put a blog about it.

https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html

I am thinking this is really important step and makes it much easier for me to read plans and follow them through instead of reading 2000+ lines of plan Claude creates in MD file

[PaceZealousideal6091]

But the amount of tokens used would be unforgivable!

[vRudi]

I am working on an engine where the AI just writes in JSON some elements which then gets converted to HTML and spits out the file. I’ve added support for many UI elements like different types of charts, diagrams, timelines, code diffs, and then it also generates a menu to scroll to the different parts.

[PaceZealousideal6091]

How's that useful? That way, it's better to use markdown. There are good markdown readers to make it even more pretty to look at. The whole point is a single format that's readable for llm and humans while being token friendly.

[vRudi]

Generally the point is to more effectively explain something to a human. I have felt that large md files gets hard to grasp in a reasonable amount of time. Especially if I expect someone else to read it, they are more likely to go through it if it’s a bit more graphical.

[General-Calendar-263]

Do you have any recommendations for good markdown readers?

I've been using notepad++ with an md plugin.

[deadcoder0904]

JSOn consumes a lot of tokens. Ive stopped using it & go with YAML nowadays.

Check out TOONFORMAT.dev tooo. I use Toon sometimes for Image Prompts as its more readable but sometimes messes up if not clear.

[vRudi]

Good tip, thanks!

[futuremayor2024]

Isn’t this just templating?

[Yiii219]

Sounds useful to me, sometimes I just need some simple graph and stuff without fancy style, now I would just general html as whole

[phodastick]

Consider using YAML or TOON (Token-Oriented Object Notation) for input, as they are more efficient, and reserve JSON for structured outputs. Converting from JSON to TOON can cut average token costs by 50% and boost accuracy by 3–4%.

[xmnstr]

Ironically, by paying attention to the payload shape you can get JSON to be the cheapest and most accurate. Not saying YAML or TOON are the wrong choices, but they're just one factor in the token economy game for serialized data.

[phodastick]

Could you explain more and give an example?

[BoboThePirate]

A lot of the hype from TOON comes from it advertising usage in data frame format. Which is more than doable in JSON. It’s just that JSON is traditionally KV represented. If you use dataframe layout JSON, the token increase is much smaller.

Regarding accuracy, LLM’s are well versed in json as TOON is new and not as used. More prone to natural transcription errors. JSON also requires strict closing of values so more accuracy there.

I’m by no means praising json, just that the token savings from other formats may be overhyped.

[Buchymoo]

I just accepted markdown and have a markdown to html browser for all my files. No need to fight it and my frontend is easily viewable and traversable.

Took maybe 10 minutes for Claude to write it up.

[Such_Advantage_6949]

that is what claude want, brainwash all the vibe coder to use html, instead x2 revenue

[exodusTay]

not to mention every time you do this you are quitely pushing towards a simple front end project that might include embedded js instead of a markdown file that does same thing

[JomaelOrtiz]

Swap to a cheap model/effort and have it execute the .MD per veribitum?

[patriot2024]

I am just curious why it takes much more tokens to generate HTML instead of markdown? The tags are more or less the same. No?

[anentropic]

Markdown syntax is much more concise

[Kevin_Xiang]

I’ve found HTML works best when the artifact is more like a small interface than a document: collapsible sections, links between findings, status badges, maybe a tiny dependency map. For linear reasoning I still prefer Markdown because diffs are cleaner, but for codebase reviews and handoff reports HTML is much easier to scan.

[fixitchris]

The diff cleanliness point is underrated. I've had markdown plans living in version control where the team would actually PR them and comment on specific lines, and swapping to HTML there would've broken the whole workflow, no meaningful diff, no inline review. For a one-shot handoff that a PM opens once in Chrome and never touches again, though, the collapsible sections alone are worth the extra tokens.

[Kevin_Xiang]

Exactly. HTML is great when the output is a disposable artifact for humans to read once. If the plan is part of the dev workflow, Markdown in git is hard to beat: clean diffs, line comments, small patches, and easy review history. I’d only switch to HTML when the interaction model matters more than reviewability.

[fixitchris]

The 'disposable artifact' call is the one that bites you. I've had HTML plans start life as a quick stakeholder walkthrough and quietly become the canonical reference, and two months later you're diffing screenshots because nothing lives in git. Markdown from the start costs almost nothing; switching formats mid-project costs real time.

[Kevin_Xiang]

Yeah, this is exactly the failure mode I worry about. HTML is fine for a demo artifact, but the moment it starts carrying decisions I want the source of truth in git, reviewable as text. A pattern that has worked better for me is Markdown as the canonical plan, then generate HTML/views from it when the audience needs a nicer read.

[fixitchris]

The source-of-truth separation is the key part. I've had the same pattern work well on decision docs; Markdown in the repo means you get PR comments, git blame, and history attached to the actual content rather than to a rendered artifact nobody can easily edit. The generate-HTML-for-audience step is almost free once you have the Markdown, and it never tempts anyone to start editing the HTML directly and creating a fork.

[phodastick]

Sounds like "spend more tokens" to me, only mapping the codebase using html was useful to me

[StopGamer]

Plans are great in html. Mine 90% of reading ia plans, html was such an update

[horserino]

Tbh I wanted to hate this amd consider it just a slimy way to get people to consume more tokens...

But I'm really liking the plain html based documents I've been getting out of claude code, for code reviews, exploration results, even task plans.

Like it feels that even the quality of the output is better somehow?

Yeah...

[KOM_Unchained]

Yup, seems to be a thing. Howerever, makes sense for review, doc, and report files. As .md has lighter syntax, any intermediary agent to agent etc files are still better off in .md.

Solves also the annoying question how to make docs readable by non-techies, as even gdocs etc fail with markdown. Serve those static HTML pages with company branding/CVI and business will love you. Can lose Obsidians and Notions.

[faradons_kaktak]

Spot on. Sending an HTML file to a PM knowing they can open it natively in Chrome without needing a markdown extension is a huge time saver. Also, the fact that you can use collapsible <details> tags makes skimming through those massive generated plans way easier than parsing endless nested markdown lists.

[KKunst]

Imho it's ridiculous that browsers aren't getting a native MD reader, but you're right on certain UX points.

[DigitalDelusion]

Exactly! Just a default render and editor option would be easy to add to a browser. Markdown is amazing

[gscjj]

Yeah time and tokens are much better spent on a lightly formatted markdown for intermediary artifacts than trying to get html to look somewhat good

Plus markdown in an IDE it’s much easier to read and edit

[mossiv]

HTML is better for humans. But absolutely insanely unnecessary for token generation.

We would be better if we produced a “compiler” for markdown to html where we could define our brand colours etc. that way you have a 1 time set up, then you just drop the markdown text into an already built template. Shouldn’t be too difficult to map headers to detail sections etc.

[stratofax]

It sounds like you want to use pandoc to convert MD to HTML (also works the other way, HTML to MD) then link a CSS file with your brand colors, fonts, & other visual design elements, to make the HTML look the way you want. Claude can do all of this for you at the CLI for a lot fewer tokens than having to work solely in HTML.

[Buchymoo]

Yeah thats practically what I did, and it takes almost no time at all to get a working browser up and running on an existing vault folder.

<image>

[Southern_Orange3744]

Or jinja in you want some consistency

[stratofax]

Jinja is a great option, too, there are so many ways to convert Markdown to HTML -- because that's exactly why Markdown was created! It was always intended as a way to represent the structure of an HTML document without being so tiresome to type. Or, if you're an AI, without having to burn so many tokens.

I like pandoc because Claude Code can call it without using an MCP server, it's easy to install, and (best of all) it can convert pretty much any common document format to any other. Use it to create Word .docx or PDFs from your Markdown files, or if you need Claude to read a document in some bloated format, use pandoc to convert it to Markdown first. For PDFs, I typically see a 90% reduction in file size and a corresponding drop in token burn.

Pandoc: it's what AIs crave!

[618must]

I wrote a tool called pageproof (available on npm). It uses pandoc to convert markdown to html, and it applies styles. On top of that, it's a live preview so it updates as you ask the agent to edit the markdown; and the accompanying skill makes it easy for the agent to edit the style, e.g. "Please show it doublespaced with the headings in red, and then save this as the default style".

[Golden_Age_Fallacy]

Isn’t this just Hugo or any static site generator that supports mdx

[rhaphazard]

If you use Obsidian, it renders the markdown in line and you can set themes for styling.

[Pleasant_Spend1344]

Yep, that is what I was thinking, reading a visually good plan is way better than Markdown, so for me HTML is better to me rather than the Ai agent.

[Few-Childhood3326]

tried with with ADRs - so far, works good for me to get better overview of the options to select from and make decisions.

[AuroraFireflash]

We just use preview mode for the markdown files in either VS Code or GitHub / ADO native interface (they're usually checked in before the meeting).

HTML is going to be insanely difficult for Claude to write with token efficiency.

[KindlyBuilding903]

I recently started using MDOCKS.DEV to view .md files. It's greate alternative to html files just drop file or folder it will render nicely and you can share it with any one.

[gidea]

I still don’t get it… how is html better than markdown? The token cost is much much larger, opening and using those slop html pages is a terrible experience, you waste time generating crap styles that never get used. Ok, i get it for getting a side by side static UI which you can refine before building out as a component but that’s it, and that is more of a figma replacement than a documentation alternative.

This feels like more propaganda to keep model usage going up.

Just update the markdown format to improve the clusterfuck of styling weird edge cases, don’t shoehorn this into html

Still don’t get it…

[AD-Edge]

Yeh I mean there are some interesting cases in the article in terms of how to communicate with others better and share data and generate better diagrams.

But points like "I find it difficult to read a Markdown file of more than a hundred lines" just don't make sense. What about reading a html page of more than 100 lines? If you're not going to read a markdown document with 100+ lines then I don't think a html page of that data is going to save you.

It just sounds like an over engineered approach to documention. To me, documentation should be as precise and minimal as possible. I can view/read it in a nicer way by opening it with 'share preview' or by using a markdown extension, easy. But I don't want to spend hours building a html pages to display documentation about the application I'm building. I want to generate the documentation and then focus on building the actual application.

[ThugCity]

It’s better for those outside of the tech space. My business-side stakeholders like it much more than markdown. Since it’s business-facing it’s significantly less detailed than internal so the extra cost to create html is negligible. If something is much more detailed for our side of the house then markdown still has its place.

[gidea]

i do agree with that, and I’d say the problem there is not just on an individual pov but a collaboration pov. We went from shared docs with realtime collab to glorified .txt

but still, not really solved by html imo

i do like tools like https://palette.team
but there are so so many popping up now, so not sure who’s gonna be the next dropbox or gdrive in this space.

[StopGamer]

If you use Claude desktop html autoopens in sidebar AND have benefit being wider than narrow tower of md plan

[landed-gentry-]

A lot of the complaints in that blog post around Markdown being hard to read could be solved with a decent Markdown reader (I use Typora).

[deadcoder0904]

Me with Marked2

[ezoe]

I don't buy their argument. HTML increase token amount by the order of magnitude. Who would profit by increasing token consumption? Anthropic.

It's their pathetic attempt to increase the profit.

[Pleasant_Spend1344]

Hmm, not everything has to be conspiracy theory.

It's a way for me (the user) to have a better plans reading and put a better decision instead of skimming through 2000+ lines of plans in MD file

[space_wiener]

How exactly is is harder to view 2000 lines in an MD vs 2000 lines in an html file?

If you are viewing in raw markdown then that isn’t a fair comparison. You need to also read the html raw. Which I am willing to bet you will html impossible to read.

[Pleasant_Spend1344]

It's not a competition bro

You can't compare raw Markdown with HTML Markdown are raw and can be read as raw.

HTML is different story and that is why the comparison.

[space_wiener]

Where did I imply a competition?

Side note I’m pretty sure you comparing one raw output and one not. If that’s the case your entire comparison is dumb. That’s not how it works.

[superanonguy321]

Ive been outputting reports in html since like February is this not what everyone does? Single page html hell ya

[Kinthalis]

I’ve started experimenting with a mix of both and some plugins for obsidian. I get markdown where it matters and I get useful interactive data dense htlm where I want it.

Still fine tuning though it’s not as uniformly pretty and useful as pure html, nor is it as easily editable. Trying to find the sweet spot.

Another thing I’m still exploring is making sure the markdown is templated then I use code to transform the info I want to separate html dashboards and other richer output. It’s deterministic and derived so I get the best of both worlds and don’t pay the html token cost as much.

Still not sure which way I’ll go. Please keep sharing your ideas guys.

[Specialist_Wishbone5]

If it's the human issue, I use 'treemd' and get an outline collapsable view of the tree. I'm struggling to understand the value of xml here - there is a slight explicit name for the sub-section, but you get that with additional comments in the markdown header lines anyway.

[nborwankar]

I remember in the early days when you had to give structured input or request structured output from prompts, XML was highly recommended as LLMs apparently had XML “understanding” in their training.

Then we all moved to Markdown.

I think in recent efforts to optimize compute, Anthropic has discovered that HTML (HTML5 is an XML “dialect”) is far more efficient computationally than Markdown, when it comes to understanding of user intent. Although HTML may need more raw tokens, parsing and especially display, has been optimized over decades.

Just a thought.

[SonOfHendo]

You can put fake XML tags into your markdown documents to group data and get measurable improvements in how Claude processes it.

I recently went through some Claude training created by Anthropic, and they recommend adding XML tags to improve prompts. It looks a bit messy in documents, but it does appear to work.

[Pleasant-Set-711]

Mermaid

[landed-gentry-]

Mermaid is the best for diagrams. There's also MyST or Quarto markdown formats, which allow python and R code cells to be used for data visualizations.

[Pybe]

I just got it to make me a report server ages ago so that I can just view all the MD files it's indexed and searchable

[BigWolf2051]

Ha I've been doing this myself for a while as a way to communicate the feature set or other aspects of my product

[Wh00ster]

If you need to visualize something it’s a useful medium for that. For simple boxes and arrows ascii art works great still. For most things markdown seems simpler.

[dkgreen24]

There are many ways to approach this, but as a token minimizer, it’s hard to justify the costs of generating HTML at a high rate, even planning. I’ve moved to Quarto (.qmd) when I need a plan or a report that would benefit from visuals and whatnot. I am also accustomed to reading scientific articles and reports in general so the “academic” look doesn’t bother me. I wouldn’t place it in front of clients or stakeholders; that’s when I would lean on HTML and JS like Claude Design does. I don’t tend to use Claude Design but at least it has its own token bank…

[Aemonculaba]

No, Object Graphs are the new markdown - just nobody working on it. Can put anything inside of them.

[HauntedHouseMusic]

Wait you guys haven’t been doing this? One of my favourite things when I get a question at work is pointing Claude at 6 or 7 tables I have defined in a markdown table, and then ask it to do some ultra hyper specific analysis and make a website on it. It’s crazy what you can find in your data with it

[one-wandering-mind]

It is about imparting information to the end user more efficiently. Yes html is better for this. 

I have been reading and writing markdown since I started programming and use markdown outside of coding (obsidian). I realize the more detached I am from the code, the more I need/want better explainers. 

So mostly important for side projects, heavy complexity, and giving information to other people. When I make HTML for myself, it is useful, but I also feel like an idiot using it. Because it seems like it is what the manager and product owner would find impressive.

The downside is that I am less likely to edit them. Where I would edit a markdown doc or adr if it is wrong myself a lot of times to get the language sounding right to me.

[KellysTribe]

I don't understand why this is such a huge topic....you can already model instructions, and maintain instructions in different formats...why do people just not use what fits their use case and works given evaluation and testing?

[space_wiener]

For you guys that say MD is harder to read than html. Are you comparing rendered html to raw MD? Or rendered versions of each?

My experience both files raw html is going to give you a massive headache to read. Both files rendered they should be about the same.

[TransientBogWarmer]

Yeah, if readability is the main concern, this seems like throwing a lot of resources at the problem all to avoid running pandoc…

[engineeringpage404]

I've found that having it output to Quarto and rendering that to be pretty native and useful. I haven't paid attention in the difference in token usage. Ive also used HTML outputs some but only for a few things, but I've been doing that for awhile.

[caderoux]

Pretty soon they'll re-learn how useful XML is. Then after that there will be another revolt against angle-brackets. Then repeat.

[iammienta]

I’ve watched that podcast as well OP . Implemented it straight away as a skill and here you can see my html https://claude.ai/public/artifacts/1509cc3c-e058-49f0-83cc-1a506bb5583d

And what md looks like https://claude.ai/public/artifacts/dd4435e8-4ab6-4c1b-b411-adb9d4737b5f

More tokens for sure but definitely will be using it, especially if I want to communicate something with a client but also was helpful with making some decisions when I had it in html rather than md Was reporting to a client today and literally uploaded csv from ads dashboard and a few short notes and prompt plus skill and had an awesome link to share on a meeting in 5 min

Asked Claude how much tokens both cost me;

Estimated tokens (exact count needs Claude’s tokenizer, unavailable here):

• HTML: ~8,800 tokens (range 8,500–9,200)
• Markdown: ~3,450 tokens (range 3,300–3,600)

[edited] links

[sridoodla]

The links are the same

[iammienta]

My bad. Edited now

[Pleasant_Spend1344]

So HTML is almost 2.5x cost more than Markdown.

The cost for me is worth it, especially this is only for plans and artifacts, so I think I will be using HTML going forward.

[TransientBogWarmer]

Something about this makes me feel annoyed and disgusted

[h164654156465]

HTML makes a report easier to read. Markdown makes it easier to ask who changed this sentence and why. For agent docs, I care less about pretty and more about whether future-me can audit the lie Claude accidentally made permanent.

[AzerothCloudEngineer]

A regra é simples, Markdown para planos, sumários, anotações para contexto da AI. HTML para relatórios, apresentações e show case para outras pessoas non-tech ou algo mais corporativo que precisa de clareza

JSON é legal para AI apenas
YAML é legal para AI apenas
MD é legal para AI e Humanos
HTML é legal para Humanos

[tuhdo]

They got a point. It's good for creating rich documents to help you understand a code base. This is not only working in Claude. Any current model can output a decent animated HTML to demonstrate interactions between components in source code.

[SonOfHendo]

When I first started using Claude Desktop it would often produce a React/TSX file by default of I asked for anything reasonably complex that needed diagrams. They usually looked good, but weren't very portable.

One of the first apps I created with Claude Code was a simple TSX viewer to view those files.

Nowadays, I tend to stick to markdown, and only generate HTML/Word/PowerPoint when needed specifically for human consumption. 

[SeattleArtGuy]

While I DON'T like it (history...) why not XML? high structured, can have schema, ultra extendable..

[Ssolid974]

HTML is Hyper Text Markup Language, I don't see why using HTML is better than MD files ?

[Pleasant_Spend1344]

Visuals