Markdown is for humans

Developers and nerds have seemed satisfied with Markdown as a plain text format for a long time. Now, I see Markdown approaching the edges of the mainstream. I casually mentioned Markdown in conversation with some of my schoolteacher friends and one of them nodded with recognition. That’s new. Maybe it’s because Google Docs enabled Markdown editing back in 2022. Or because, in 2026, Apple Notes enabled the import and export of Markdown-formatted documents.

Markdown’s creator, John Gruber, wrote that the surge in Markdown’s popularity could be attributed to widespread LLM usage. And yeah, I’ve definitely seen LLM output filled with Markdown. Maybe the schoolteachers are, too.

Whether I’m speaking with software developers, technical writers, or schoolteachers, though, I see many of them misunderstanding what I think is the innovation of Markdown. Compared to the other historical plain text markup formats like Setext and BBCode, reading and writing full documents in plain text is easy and not syntactically perilous. Yes, Markdown does lend itself to rendering simple rich text and HTML documents. But it’s even more useful as a way to increase the information density of 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 formatting plain text. If everyone agrees to the same basic conventions, plain text can be significantly more expressive than a string of unformatted characters.

In the end, I’m grateful for projects like CommonMark working towards a complete syntax specification of Markdown. But I worry that some of their decisions lean in the direction of harder-for-humans-to-read Markdown. I already see Markdown documents written by authors who think of Markdown as a feature-complete markup language (it’s not) used to render richer documents. Maybe you, too, have seen an order list defined in this way:

1. The first list item.
1. The second list item.
1. The third list item.

Because GitHub Flavored Markdown, CommonMark, and a bunch of other implementations “correctly” interpret the intention of this as rendering a normal ordered list in HTML:

1. The first list item.
2. The second list item.
3. The third list item.

It’s my opinion that if you’re writing a list long enough, or complex enough, to benefit from using 1. as an auto-incrementer, maybe you shouldn’t be using Markdown.¹ Similarly, if you need to do some of the stuff that CommonMark implements for complex lists (see: “There can be any number of blank lines between items” and “loose lists”; insert blank HTML comments to generate two consecutive lists; consecutive list items with sub-indentation), consider other tools for building documents or documentation. CommonMark’s rules and tests are helpful, but they’re ultimately best for the machines and precarious for humans.

On the other hand, CommonMark and other Markdown specifications include some really great ideas that make Markdown-as-plaintext even better. I like Extended Markdown’s simple definition lists:

Lugger
: A small sailing vessel having two or three masts and a running bowsprit,
   carrying lugsails.

And I like task lists as popularized by GitHub Flavored Markdown:

- [x] Watch *Peter Hujar's Day* (2026).
- [ ] Watch *Cemetery of Splendor* (2015).
- [x] Watch *Rose of Nevada* (2025).

Slack, Todoist, Google Docs, and so on, have cemented Markdown as the way to jot down short, rich-text-formatted messages. Markdown specification, implementation, and interoperability do matter and will likely matter more in the future. I just write this as a reminder that Markdown is for humans. My newlines should be for me primarily, the machine secondarily. And the fewer {id: "unique-header-identifier"}s I need to insert in my document source, the better.