Markdown Is for Thinking. HTML Is for Showing.

I read this post about HTML being more effective than Markdown for Claude Code: original post →

And I get the point.

HTML is obviously useful.

If an agent creates a long report, spec, architecture map, or design explanation, HTML can make it much easier to read. You can add layout, diagrams, colors, tabs, buttons, sliders, whatever.

For sharing with other people, HTML is probably better most of the time.

But I don’t think HTML is the next step of Markdown.

I think they do different jobs.

Markdown is not great because it is visually rich. It is great because it is almost invisible.

You open a file and write.

No layout.
No design choices.
No “how should this look?” before “what am I trying to say?”

That is important.

When I write in Markdown, I feel very close to the thought itself. It is minimal enough that I don’t think about the format, but flexible enough to hold almost anything: a startup idea, a personal note, a technical plan, a scientific paper draft.

It does not make the idea look better than it is.

Which is sometimes annoying.

But also honest.

If the thought is weak, Markdown does not save it. If the logic is broken, a nice card layout will not hide it. If the sentence is fuzzy, you see the fuzziness directly.

That is why words matter so much.

In science, people fight over words for a reason 😄

“Shows” is not the same as “suggests.”
“Important” is not the same as “statistically significant.”
“Possible” is not the same as “likely.”

One word can change the whole meaning of the claim.

This is also why I still think books are one of the best ways to learn.

When you read a book, you don’t get the model for free. You get abstract words, and your brain has to map them into something concrete.

You build the picture internally.

And when you can’t build it, you notice.

That moment is valuable. That is where real understanding starts. You can feel exactly where the concept becomes blurry.

Visuals can help a lot here. Diagrams, interfaces, HTML artifacts, interactive explainers — all of this can speed up understanding.

But sometimes they speed it up too much.

You see the diagram and feel like you understood the thing. Maybe you did. But maybe you only recognized the shape.

Words are slower, but they force more work from your brain.

And for deep understanding, that work is the point.

So for me, HTML is not a replacement for Markdown.

HTML is a second angle.

Markdown is where I think.
HTML is where I show.

I would still start with words.

Then, when the idea has enough structure, I can ask AI to turn it into HTML: make it visual, navigable, interactive, easier to share.

But the HTML should wrap the thought, not replace it.

Because the main artifact is not the page.

The main artifact is the idea becoming precise.

Markdown helps with that because it stays out of the way.

HTML helps later, when the idea needs to be seen by other people.

Both are useful.

But if I need to understand something deeply or express it with maximum precision, I still want the words first.