Markdown Has 24 Flavors. The Universal Subset Won.

Karl Voit is right: Markdown has at least twenty-four mutually incompatible flavors at the time he counted them¹, and the CommonMark authors agree the original syntax is ambiguous². The win is the small universal subset — owned by no vendor, read by every reader from cat to ChatGPT. That subset is what you are actually betting on.

Most defenses of Markdown begin by denying the critique. This one begins by conceding it, because the concession is where the real argument lives. Headings, bold, italics, lists, links, paragraphs, fenced code: those seven shapes render identically across CommonMark, GitHub Flavored Markdown, every static-site generator, every browser, every terminal cat, and every frontier language model. The flavors are the noise around that signal.

The critique: Voit is right, and the spec authors say so too

The case against Markdown is real and the evidence is on the spec's own home page. Karl Voit's Markdown Is a Disaster¹ documents at least twenty-four mutually incompatible flavors and ambiguous parser behavior; the CommonMark working group concedes the ambiguity outright in its first paragraph². The concession is the entire reason CommonMark exists.

Voit's essay opens with a careful self-description. "This is a — hopefully qualified — rant about the use of Markdown as a Lightweight Markup Language (LML) instead of other LMLs that are more qualified to do the very same job."¹ The framing is honest about its temperature, and the evidence underneath the temperature is unfortunately solid.

His central data point is the count. "twenty four different Markdown flavors. And I would not be surprised if that number is much lower than the actual number of Markdown flavors out in the wild."¹ He cites the Markdown Monster reference catalog. The number is real, it is reproducible, and at three years past his publication it is almost certainly higher than twenty-four today.

The CommonMark working group does not disagree. The first thing the current CommonMark Specification, version 0.31.2 (2024-01-28), tells you about why it exists is this: "John Gruber's canonical description of Markdown's syntax does not specify the syntax unambiguously."² That is a verbatim concession, on the spec's home page, written by the authors actually shipping the standard. The critique is not a smear from the outside; it is a load-bearing acknowledgment from inside.

Voit's own follow-up on Hacker News tightened it further. Replying to a commenter who had written that Markdown "won," he answered: "MD did not 'win'. That would imply that no alternative situation would be possible any more. It's just the most popular Lightweight Markup Language (LML) at the moment."³ That is the strongest charitable framing of the case against, in the words of its author. Hold it.

The pivot: the universal subset is the part with no flavors

The flavor problem is real at the extension layer and absent at the core layer. Strip the vendor-invented extensions — wikilinks, callouts, dataview queries, embeds, math, diagrams, front-matter — and what is left is a small subset that has not meaningfully changed since 2004. Every parser, every renderer, every reader implements that subset identically.

The seven shapes underneath the noise are deliberately boring. Headings with #. Bold with **. Italics with *. Bulleted lists with -. Numbered lists with 1.. Links with [text](url). Paragraphs separated by a blank line. Code with a triple-backtick fence.

That set is the universal subset. It is what CommonMark §1.1 describes in tracing the format to its origin: "Markdown is a plain text format for writing structured documents… It was developed by John Gruber (with help from Aaron Swartz) and released in 2004 in the form of a syntax description and a Perl script (Markdown.pl) for converting Markdown to HTML."² Twenty-two years later, that 2004 description is still the part every parser implements.

The GitHub Flavored Markdown specification, version 0.29-gfm, settles the question of whether vendor extension necessarily breaks the universal subset. GFM is defined as "a strict superset of CommonMark"⁴ — every CommonMark document is a valid GFM document, and renders the same way. Tables, task lists, strikethrough, and autolinks are added on top, each plainly labeled as an extension. The contract is not that everyone agrees on what Markdown is; the contract is that everyone agrees on the floor.

Anil Dash, in How Markdown took over the world, names the consequence of that floor: "Nearly every bit of the high-tech world, from the most cutting-edge AI systems at the biggest companies, to the casual scraps of code cobbled together by college students, is annotated and described by the same, simple plain text format."⁵

He adds the GitHub-shaped corollary: "On GitHub, the platform that nearly every developer in the world uses to share their code, nearly every single repository of code on the site has at least one Markdown file that's used to describe its contents."⁵

Mat Duggan's Markdown Ate The World (2026-03-23) puts the LLM-substrate fact plainly: "with the rise of LLMs and their use (perhaps overuse) of Markdown, we've reached peak .md."⁶ The largest language models on the planet emit Markdown as their default structured output. They do it because the floor reads the same everywhere they look.

The argument: own the subset, not the syntax

The choice for an archive of plain text is not "pick the winning syntax" — it is "write to the universal subset, accept the rest as vendor lock." Voit is right that Org-mode has a cleaner grammar and that AsciiDoc and reStructuredText are more capable. The archive question is narrower: which substrate will every reader your notes outlive still understand?

The CommonMark spec quotes a phrase the critic side rarely concedes. "Websites like Reddit, StackOverflow, and GitHub had millions of people using Markdown."² That sentence is in the spec because it describes the network effect that made standardization worth doing in the first place. The universal subset is the part of Markdown that those millions of users share, not the part that any one of those websites added.

The proof that the floor holds is in the boring cases. A # Heading and a **bold** word render identically in Reddit's editor, GitHub's README viewer, every popular static-site generator, every Markdown editor on every desktop platform, and a terminal less session if you do not mind seeing the asterisks.

They render the same way when ChatGPT, Claude, or Gemini emit them — and the same way when cat prints the file to stdout and the asterisks are the formatting. That is one bytes-on-disk representation that survives every reader you are likely to use this decade.

The boring conclusion is that "Markdown won" is the wrong claim, and Voit is right to push back on it. The defensible claim is narrower and harder to attack: a specific, small subset of Markdown won the floor, and the floor is the part you wanted owned by no vendor in the first place.

The practice: write the floor, stay legible to every reader

If the bet is on the universal subset, the discipline is on the writer — write the seven shapes by default, treat every extension as a vendor-scoped choice, save the files as .md on disk, and accept that the subset cannot carry images, tables, math, or diagrams. Three rules carry the weight; a fourth names the honest limit.

1. Write only the seven shapes when you want maximum portability. Headings, bold, italics, bulleted and numbered lists, links in [text](url) form, paragraphs separated by a blank line, fenced code with triple backticks. These render identically in CommonMark, GFM, every popular static-site generator, every terminal pager, and every LLM. Cross-link the complete Markdown cheat sheet for the syntax reference.
2. Treat every extension as a deliberate, vendor-scoped choice. Wikilinks render in Obsidian and break in Reddit. Callouts render in Obsidian and break in cat. Dataview queries render in Obsidian and do not exist anywhere else. They are not wrong to use; they are wrong to use without knowing that you have just left the floor. Wikilinks are not plain Markdown explains the most common case in detail.
3. Save the files as .md on disk, not inside a vendor's database. A folder of Markdown files is not the same archive shape as a SQLite blob, a proprietary format, or "Markdown stored inside an app." The universal subset is a property of bytes on disk. Your notes can be a database without a silo makes the substrate-vs-silo case; text files are a user interface makes the file-shape case.
4. Honest limit: the universal subset cannot carry everything. Images that travel with the document are a known break — Markdown's image syntax points to a path or URL, and the moment the path moves the link rots, which your Markdown is portable until you add an image documents. Tables are GFM, not core. Footnotes are an extension. Math is an extension. Diagrams are an extension. If a piece of writing genuinely needs those, pick the extension you are paying for, and read the receipt.

The discipline is not "Markdown solves portability." The discipline is "the part of Markdown that every reader supports is the part you want your archive in, and the rest is a choice you are accountable for."

Frequently asked questions

Why are we still using Markdown? Because the universal subset — headings, bold, italics, lists, links, paragraphs, fenced code — renders the same way across every CommonMark-compliant parser, GitHub Flavored Markdown,⁴ every static-site generator, every terminal cat, and every large language model. The flavors disagree about extensions; the floor does not.² That floor is owned by no vendor.

Is Markdown obsolete? No — the strongest evidence is the adoption curve continuing in 2026, not the 2004 launch date. Anil Dash's January 2026 defense of Markdown⁵ reached 440 points on Hacker News⁷; the recurring "Why are we still using Markdown?" thread reached 233 points the same quarter.⁸ The conversation stays live because the format keeps shipping into new tools.

What is wrong with Markdown? Karl Voit's Markdown Is a Disaster¹ documents the core complaints: ambiguous original syntax, at least twenty-four mutually incompatible flavors at the time he counted them, and parser-dependent rendering. The CommonMark working group agrees: their spec opens by stating that "John Gruber's canonical description of Markdown's syntax does not specify the syntax unambiguously."² That is exactly the reason CommonMark was written.

What is the alternative to Markdown? Voit recommends Org-mode syntax (he calls it "Orgdown").¹ Real alternatives also include AsciiDoc and reStructuredText, both with stronger formal grammars and richer feature sets. The trade-off is adoption — none of them is read by as many editors, parsers, browsers, terminals, and language models as the universal subset of Markdown. Pick the substrate with the largest reader population.

Why is Markdown so popular? CommonMark traces it to a network effect: "Websites like Reddit, StackOverflow, and GitHub had millions of people using Markdown."² Anil Dash adds that on GitHub, "nearly every single repository of code on the site has at least one Markdown file that's used to describe its contents."⁵ Once it's read by every developer's tools, every adjacent tool reads it too.

Are there too many Markdown flavors? Yes — twenty-four at the time Voit counted them,¹ probably more today. The escape hatch is to write only the universal subset every flavor implements identically. Extensions are useful and legitimate, but each is a vendor-scoped choice; a wikilink, callout, or dataview query leaves the floor on purpose. Wikilinks are not plain Markdown walks through the case.

Does it matter that Markdown is "popular" rather than "best"? No — Voit is right to insist on the distinction. He wrote on Hacker News that "MD did not 'win'… It's just the most popular Lightweight Markup Language (LML) at the moment."³ For an archive of personal writing, that is the right property. "Owned by no vendor, read by every reader" is the bet; "best grammar" is a different question.

Why do LLMs read Markdown so well? Their training corpora are saturated with it — GitHub READMEs, Stack Overflow answers, Reddit threads, and nearly every developer tool that produces structured prose. Mat Duggan called the result "peak .md."⁶ Why an LLM reads your Markdown better than an export explores what that means for note-takers whose archive will be read by models as well as humans.

The argument we are answering is Karl Voit's, and the part of it the CommonMark working group also concedes is the part this essay leans on; the rest is the universal subset doing the boring work of being legible to every reader you are likely to use.

This essay builds on Karl Voit's critique¹ and the CommonMark working group's own honest framing of why a spec was needed.² MNMNOTE writes the universal subset of Markdown — headings, bold, italics, lists, links, paragraphs, fenced code — to plain .md files on your device, the same shape every other Markdown reader on the machine already understands. The substrate is at mnmnote.com.