Is HTML the New Markdown? (Claude Code)

Added: 2026-05-12

[00:00:00]What if the way you're communicating with your agents is restricting how good their output can be? Well, a senior engineer at the Claude Code team just published this article making exactly that case. And it already pulled 9.3 million views in just two days. His argument is that HTML is more powerful than markdown if you know how to use it.

[00:00:18]So, I thought I'll show you what made this article land with millions of people and the four levels by which you can use HTML to work better with your agents. Let's dive into it.

[00:00:26]>> [music] >> So, this person, Tariq, he's part of the technical team of Claude Code of Anthropic, and he recently published this article like two days ago that's titled Using Claude Code, The Unreasonable Effectiveness of HTML. And you can see it went quite viral. Let's see, it already has 9.3 million views 48 hours after it was written. And I read the whole thing and it is actually quite useful and I tend to agree with his points in here. So, I thought it might be useful for you as well. But just to go through the sort of key points that he mentioned here as his core, he says he's saying that markdown, even though it has become the dominant file format used by agents, which are present when you're making like your Claude.mds or your agents.mds or your design.mds, since agents have become more and more powerful, he argues that markdown files are actually sometimes quite restrictive. Especially if you use markdown files for planning or as output, it is actually quite difficult to read or at least takes time to read if it's more than 100 lines and I tend to agree. That's why from my experience and it seems from Tariq's as well, there is now this sort of growing cluster of people who have started preferring HTML as an output format instead of markdown.

[00:01:37]And if in case you don't know the difference between those two, both of these in their essence is all just text, but the key difference between them is how they render to you as the user. And by render we just mean how they appear on your screen. For example, if you look at your markdown files, all they are are text files with basically these hashtags or number signs connoting the heading or the bigger text in your whole document.

[00:01:59]And then you have the body written down in here. So very clean, still very readable by people, but if you just compare it with HTML stands for HyperText Markup Language, you can see how much more visual it is. It can render colors for you. It can render tables and so on. And in fact, just to go through some more examples in here so you can differentiate between the two before we go into the actual use cases.

[00:02:20]Let's say you're reviewing a report for an API outage incident. If you render it in markdown, it is still formatted like this where you need to read from top to bottom. But if you are rendering it via HTML, you can see it's much more visual.

[00:02:32]You can point the viewer to key parts in here. Like for example, this colored box with the root cause. If you think that is more important to be communicated in order to drive your point better. If you have some sort of customer report, it is so much easier to visualize everything using HTML versus like a markdown document which just list those data points for you. This is especially true when it comes to planning which is something that we'll show more later.

[00:02:55]But let's say you are planning for your next sprint or your next project. If you just have those rendered in markdown, it takes much longer to review them just because of the nature of how they're being rendered versus if you render them visually through HTML just like this one. So given that, when should you now use HTML instead of markdown? So I'll be giving a few examples, but if you want to try this out yourself and also instantly give your agent a bit of HTML mastery with the stuff that I'll show here. You can find this skill I made which basically just summarizes all the knowledge and all examples that I will be showcasing in this video. And you can just give this whole thing to your agent and you can have it custom fitted for your own setup. So the first thing where HTML really excels in is for helping you understand things. For instance, the other day I was trying out this new printing press toolkit over at GitHub in this repository. And I actually wanted to understand how it works under the hood. So naturally, what I did is open up Cloud Code, give it the GitHub URL of this repo, and I just ask it to teach me how printing press works, which is this toolkit, and what are the general steps that it takes. Now, it actually gave me a pretty good reply in here, but one of the problems with these agents is that they are actually sometimes quite verbose, and if you're reading through just a wall of text to understand something, it is not always the best experience. And so, from here, what I just did is to ask it to build a two-way HTML page for me that basically captures all of that sort of explanations that it has, but put it in a nicer format that I can read through. And if you watched the video that I published a day ago, this is basically coming from that workflow, where I asked Claude Code to render this in HTML, and it's number one, much nicer and easier to understand, and number two, it's also much easier to present to other people. And then to take it further, because I wanted to explain specifically this step four, I just copied that part that it said, and I asked it to explain it simply, and again, it gave me this wall of text. So, what I just did is to ask it to make a separate HTML slide explaining that line, and to add it as slide two for this HTML page. And so, it was able to build that, and it was also able to, in parallel, give me this nice visual, which again is much easier to communicate with. And by the way, if you're interested in going from just using AI to getting paid for it, then check out the Robo Nuggets community down in the description. We've got founders in there who landed their first client in weeks, live build sessions where we create this stuff together, and the actual templates behind what I just showed in this video. The community's also the reason these lessons get made, so see that below if that's for you.

[00:05:17]Now, the next thing that I think HTML is quite outstanding on is when you need to explain things to other people, which is pretty much what I'm doing here, right?

[00:05:24]So, all of these slides, they are all formatted in HTML. And you can see just how much more shareable and explainable they are versus if we are viewing like a text file together, especially for non-technical people, product managers, and people who are more, let's say, output and visual-based. This type of visual rendering and icons is just so much more better experience when you need to explain and communicate things to your peers. One great example of this is the emergence of using HTML slides in place of tools like Gamma or PowerPoint.

[00:05:52]For example, this one that you are seeing, which is our Agentic AI Foundations course that we do in person as well as in the community. All of these are generated by Claude code, all using HTML. So, you can see it's more engaging, it has nice visuals, it has nice animations, and you can even create diagrams or visuals like this, which is much more visual versus having to explain everything through text. And the thing with HTML is you actually don't need to have those fancy animations in order to get some benefit from it. So, you can see here, I saw this post from Nicholas, which was actually a good application because he basically turned the article from Tariq into this interactive HTML page. And he says here that from within Microsoft, their engineers sent AI-generated HTML to coordinate between software engineers and product managers. And I can definitely see this happening because HTML like files like this are still information-rich. But apart from that, they are also much easier to read.

[00:06:42]Here's another note by Bin Liu, who is the VP for product for Agent, and they pretty much do the same thing. So, it's definitely worth exploring if HTML would be sort of a good communication medium for you and your clients or your peers in order to align better on plans and documentation. The third use case for HTML is you can actually use it to prototype things. And this is very important, especially when it comes to visual design. To give an example, what I basically asked Claude code to do is to give me 10 styles of the different HTML slides for this markdown versus HTML pack that we were building, and it gave me several prototypes that I can choose from, right? And you can see, if you were to do this sort of in markdown mode or as a plan in plan mode, then just having to read that wall of text where it describes, let's say, this prototype number seven as having a Japanese Zen theme, and then this prototype number eight to have a corporate cool theme, it doesn't have that same impact or effect versus if you just quickly see all of these visual designs in one go and have them prototype those for you. To give another good example from the article by Tariq, he gave this example prompt where he asked Claude Code to prototype a new checkout button and to create an HTML file showing that checkout button. So, I tried that prompt myself and it gave me this playground where I can tweak the press duration. I can change the starting color of this checkout button if I wanted to change the shape to be more circular. And then once I'm done with that, I can just copy the parameters in here and then paste it back to Claude Code. So, if you're prototyping, you can see with a simple prompt like that, you can easily create a throwaway HTML page that just gives you a lot more control when it comes visual assets. And just to give you a quick comparison, I sent that same prompt over at Claude Code on planning mode and it gave us this markdown formatted plan, which is okay, but you can see how different it is versus seeing it visually, right? Plan mode is probably good for some use cases, but for several instances, especially for visual matters and assets, I think using HTML is just a much better experience.

[00:08:32]And naturally, the other thing that you can use HTML for is to tweak things. To give an example, let's say you wanted to tweak the design of this website. What you can do is actually embed an HTML window like this, which just lets you tweak the elements in this website, like for example, the title size, the size of the body text. You can even have more options in here, which gives you nice sliders for let's say the saturation of the website if you want it a bit more colored. Also gives you space to adjust the kerning of the fonts, the glow of that title text is also possible. And then you can just ask Claude Code to give you more sliders depending on what it is that you want to tweak in this website. And that is all HTML based and that is just a skill that I made called tweak, which again you can just grab it below. And simply what I did here is to just invoke that skill and give it the link to that HTML file, which is basically this website that you're seeing. And then once you're done with that, similar to the other thing that we did earlier, you can just click on bake and that gives you a nice prompt in here. And if you copy that patch and give it to Claude Code, then all of those changes that you wanted made will be applied to this final website. But there you can see, because of the power of these agents with rendering these HTMLs, you can actually do stuff like this that wasn't really possible before in order to better your workflow, especially if you're in the business of communicating ideas, visually showing them, or even if you just want to understand things faster and better. So, as you can see, HTML is quite good for a lot of use cases, but there's obviously a big question behind all of this, right? Which is, what about the cost?

[00:09:56]Because as you would rightly ask, HTML would need more tokens, right? And this is a completely valid question, especially since we are living in a compute constrained environment now. And it's also why I don't think HTML will replace markdowns for everything.

[00:10:09]Markdown files definitely still have their place, but one concept that I think you should consider is the ROI that you are getting from every token that you spend. Let's say for instance that you are using HTML to explain or understand things better. If you have a lot of conversations or turns with your agent in order to understand a complex topic, for example, then that might actually end up costing you more tokens versus if you just have it visualize that same concept for you. So, instead of just talking about token usage as an absolute, it is sometimes better to just think of the lens as a return on investment. Like with the time and the tokens that you are spending with your agent, are you actually getting the return and the value from that interaction? In fact, Tariq also mentioned this in the FAQs, which I think is one of the key sections that one should read if you are reviewing this article. Basically, he says here that while markdown often uses fewer tokens, the added expressiveness of HTML and the much higher likelihood of me reading it means that you would get better overall output. And he also highlighted here some of the other drawbacks of HTML, which are important consider and why markdown I think is still here to stay. Because HTML does take longer. So, around two to four times longer to render versus markdown.

[00:11:16]And also there is another aspect around version control. So, if those aspects, if those things are important to you, then using HTML for your particular use case might not be the right thing. But there, I hope you got something from that video. In summary, I think markdown files are still here to stay. cloud.mds are probably not going to be renamed to club.html's anytime soon. But if you need to communicate an idea or have your agent communicate an idea to yourself, then having it render things via HTML may be a good idea for you. So there, I hope that was useful and if it is then consider subscribing because that helps me a lot to put out more educational stuff like this. And if you want to know how I created those HTML slides, I actually made a separate lesson for it which you can just find somewhere in this video. I'll see you guys next time.

[00:11:55]Thank you.