If one tool can make the work look more exciting, why choose a different tool that makes the work look basic?
Last week, Thariq Shihipar, who works on Claude Code at Anthropic, shared an article about HTML artifacts with some nice-looking examples. He shows what can happen when we ask an LLM not for markdown, but instead for a self-contained HTML file: a dashboard, a slide deck, an annotated diff, a report with charts, a small app. Then, we can open the HTML file and see something much more visually appealing.
I get it. Anyone who has used a harness like Pi or Claude Code knows that LLMs can spit out Markdown quickly. Very quickly. But they also write HTML with ease, and HTML can do things Markdown cannot. HTML can bundle things like layout, color, interaction, SVG, forms, and JavaScript. And web browsers know what to do with HTML. When you want to explore the output, not just read it, HTML is an excellent option.
The folks on Hacker News covered many of the technical trade-offs between Markdown and HTML, and those details are worth reading if you are looking for the most technically appropriate choice. But the thread did not make me want to choose between these two formats. It left me asking what sort of relationship I want with my tools. While the tools are new, contemplative practice has been asking that same question for a long time.
Technology Pulls at the Mind
The latest technologies often tug on our minds. Ohhhhh, someone came up with a better format, a richer preview, or a more impressive artifact. Sometimes they pull us toward something useful. Sometimes the new tech just provides a reason to avoid another day of reading, revising, and understanding. Also known as “the work.”
My yoga and meditation teachers mention this aspect of the path all the time. Not the choice itself, but the moment just before the choice. They invite us to notice the small reach, or that sense that something isn’t good enough. They ask us to investigate “why?” when we develop a preference for something shinier. For me, it’s often a voice saying something like, “if you clean out your inbox and respond to your texts, then you’ll feel more relaxed and undistracted during meditation.”
Meditation seems like the simplest thing in the world. Sitting for 10 or 20 minutes involves almost no special equipment (unless you have strong preferences). Find a seat and let the body settle. Watch the breath. Easy? Heck no. For most of us, that simplicity causes the mind to rebel. Suddenly the mind has nowhere to hide, and nothing to amuse it.
A Markdown file works in much the same way. On its own, a plain text file is boring. The one I’m looking at right now is literally just black and white, with a few colors for headers and links. Certainly not exciting or “joyful,” to use one of the words Thariq Shihipar used to describe those HTML files.
Simple is hard. Contentment is one of the five niyamas in yoga. I do not view contentment as “settling for bad tools.” I understand it as the practice of knowing when enough is enough. Simple can be a path toward a more durable joy.
Markdown Is Enough
According to John Gruber, the creator of Markdown:
Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid HTML.
Markdown is rarely the final form of the document. Markdown gives writers a place to begin. It’s a readable source that gets converted into HTML (or whatever format you need).
More than just a theory, Markdown is a tool I use. I can open a Markdown file in any editor (even though I choose vim), search it, or diff it. I can copy it out of one system and move it somewhere else.
This is another example of a pattern I have noticed with AI tools: receiving versus doing. If we ask an LLM for HTML output, it jumps right to the thing we receive. We’re probably not editing a lot of the HTML by hand. Markdown keeps the work in a format we can add, edit, and delete. I can change a word without asking the LLM to reopen the whole web app.
Markdown Can Still Do BIG Things
Markdown does not trap us in small work. I write all of my code and prose in plain text. All my blog posts, notes, recipes, class plans, presentations, and drafts exist first as Markdown. Then I run them through Pandoc into whatever output I need, including HTML slides.
For instance, when I gave a talk at the International Conference on Live Coding in Madrid, I used Markdown to work out my ideas that became an academic paper, footnotes and all, and a poster.
I would not call text “holy,” but I would call it useful and durable. Plain text has not saved me from confusion, procrastination, or bad drafts. I can make a mess in any format, but Markdown keeps the mess visible.
Of course, plain text does not save me from myself. It reminds me of the period when I got a little carried away with memes in my slide deck. Too many memes.
Markdown can become HTML. It can become slides. It can become a PDF. It can lead to inline HTML when the document needs something Markdown cannot express. The simple format does not prevent complexity. It delays complexity until complexity is necessary.
A Small Test
So when should we ask an LLM for HTML? When the output is a browser, a prototype, a small tool, an interactive diagram, or a report where layout or color changes how people understand the material. HTML works well when people need to click, compare, skim, or see a visualization.
I use Markdown when I need to think with the text, like I am doing right now. I plan, draft, and edit notes by hand (okay fine, “by hands on a keyboard”). When I want to easily track changes, see a diff, Markdown is great. It also works when I want to invite someone else who knows Markdown to copy, revise, or keep under version control. Radical even, especially when so many people love Google docs.
This is contentment with Markdown, not devotion to Markdown. While using a format like Markdown, I try to notice the moment when I reach for a richer format. For instance, when I’m working on a slide deck, I often jump to the point of compiling the words into HTML because I want to “see if the words fit” on the browser. In that moment I often just feel bored with the plain text, and want to shift to experience the fruits of my words right away. I doubt that my first compile makes the talk any better. Seeing the fancy HTML presentation is usually just a distraction, whether I’m talking about web development, the Drupal community, teaching kids to code, or whatever else. People don’t come to my talks to see polished slides. They want ideas, and I typically work those out in Markdown.
So getting back to LLMs, the next time your coding agent (should you choose to use one) offers to turn a response into a polished HTML artifact, pause for one breath. Recall your intention for the task at hand. If plain text is good enough, let plain text be plain text.
Comments