Markdown is for humans / benjamin wil
Markdown
is
for
humans
Markdown is for humans
June 25, 2026
Developers and nerds have seemed satisfied with Markdown as a plain text<br>format for a long time. Now, I see Markdown approaching the edges of the<br>mainstream. I casually mentioned Markdown in conversation with some of<br>my schoolteacher friends and one of them nodded with recognition. That’s<br>new. Maybe it’s because Google Docs enabled Markdown editing back<br>in 2022. Or because, in 2026, Apple Notes enabled the import and export of<br>Markdown-formatted documents.
Markdown’s creator, John Gruber, wrote that the surge in Markdown’s<br>popularity could be attributed to widespread LLM usage. And yeah, I’ve<br>definitely seen LLM output filled with Markdown. Maybe the schoolteachers<br>see that, too.
Whether I’m speaking with software developers, technical writers, or<br>schoolteachers, though, I see many of them misunderstanding what I think<br>is the innovation of Markdown. Compared to the other historical plain text<br>markup formats like Setext and BBCode, reading and writing<br>full documents in plain text is easy and not syntactically perilous. Yes,<br>Markdown does lend itself to rendering simple rich text and HTML documents. But<br>it’s even more useful as a way to increase the information density of<br>plain text files pre-render. Gruber summarizes it well in the same post:
Markdown isn’t really a “syntax”. It’s a set of conventions for<br>formatting plain text. If everyone agrees to the same basic conventions,<br>plain text can be significantly more expressive than a string of unformatted<br>characters.
In the end, I’m grateful for projects like CommonMark working towards<br>a complete syntax specification of Markdown.1 But I worry that some of their<br>decisions lean in the direction of Markdown that’s harder for humans to read.<br>I already see Markdown documents written by authors who think of Markdown as<br>a feature-complete markup language (it’s not) used to render richer documents.<br>Maybe you, too, have seen an order list defined in this way:
1. The first list item.<br>1. The second list item.<br>1. The third list item.
Because GitHub Flavored Markdown, CommonMark, and a bunch of other<br>implementations “correctly” interpret the intention of this as rendering a<br>normal ordered list in HTML:
The first list item.
The second list item.
The third list item.
It’s my opinion that if you’re writing a list long enough, or complex enough,<br>to benefit from using 1. as an auto-incrementer, you shouldn’t be using<br>Markdown. Similarly, if you need to do some of the stuff that CommonMark<br>implements for complex lists (see: “There can be any number of<br>blank lines between items”<br>and “loose lists”;<br>insert blank HTML comments to generate two consecutive<br>lists; consecutive list<br>items with sub-indentation),<br>consider other tools. CommonMark’s rules and tests are helpful, but they’re<br>ultimately best for the machines and precarious for humans.
On the other hand, CommonMark and other Markdown specifications include some<br>really great ideas that make Markdown-as-plain-text even better.<br>I like Extended Markdown’s simple definition lists:
Lugger<br>: A small sailing vessel having two or three masts and a running bowsprit,<br>carrying lugsails.
And I like task lists as popularized by GitHub Flavored Markdown:
- [x] Watch *Peter Hujar's Day* (2026).<br>- [ ] Watch *Cemetery of Splendor* (2015).<br>- [x] Watch *Rose of Nevada* (2025).
Notion, Discord, Slack, GitHub, and so on, have cemented Markdown as the<br>way to jot down richly-formatted messages and draft simple documents. Markdown<br>specification, implementation, and interoperability do matter and will likely<br>matter more in the future. I just write this as a reminder that Markdown is for<br>humans. My newlines should be for me primarily, the machine secondarily. And<br>the fewer []{#unique-header-identifier}s I need to insert in my document<br>source, the better.
An historical aside: CommonMark was originally dubbed Standard<br>Markdown,<br>but changed immediately to Common<br>Markdown<br>when Gruber objected. And then to CommonMark when Gruber objected<br>again. If you read the Standard Markdown introductory post linked,<br>you can see all of the reasons that led to a specification “needing”<br>to exist. Gruber had been invited to collaborate on the project,<br>but he left the CommonMark team on read. It’s clear now that CommonMark<br>would inevitably clash with the one stated goal on Gruber’s Markdown<br>project page: “The<br>overriding design goal for Markdown’s formatting syntax is to make<br>it as readable as possible.” ↩