There Is No Markdown Standard

Markdown may be the most widely used markup format ever shipped: billions of files, every developer platform, most of the notes apps on earth. And there is no standard for it. Not a stalled draft, not a dormant committee. None. The last official word on Markdown syntax is a companion page to a Perl script, frozen in 2004.

Two documents fill the vacuum. CommonMark (2014) is the standard on paper: a rigorous, testable spec for how core Markdown parses. GitHub Flavored Markdown (formalized 2017) is the standard in practice: CommonMark plus tables, task lists, strikethrough, and autolinks. If you wrote a README, an issue comment, or an Obsidian note this week, you wrote GFM.

How that settled is the interesting part, because no committee ever ratified any of it. Markdown’s standard was decided the way most real standards are: not by whoever wrote the best spec, but by whoever had the most users. It took a creator who refused to standardize, a working group he forced to rename its spec twice in 48 hours, and a product default that put a Markdown file on the front page of every software project on the planet.

The spec that refused to grow

John Gruber released Markdown in 2004: a syntax description and a Perl script. Version 1.0.1 is still the last version. Gruber wasn’t ignoring it. He was openly against standardizing it. Different sites have different needs, he argued, and no single syntax would make everyone happy.

The problem is that his description left a lot of basic questions open. How many spaces indent a nested list? Is a blank line required before a blockquote? Every implementation guessed differently. And since nothing in Markdown is ever a syntax error, files moved between tools didn’t break. They just rendered wrong, silently. Ten years in, “Markdown” was dozens of slightly incompatible languages sharing a name.

The standard that had to change its name. Twice.

By 2012, Jeff Atwood of Stack Overflow had lost patience and pulled together a working group: people from Stack Exchange, GitHub, and Reddit, with Pandoc author John MacFarlane writing most of the spec. Two years of work produced a rigorous, fully testable definition of Markdown: every ambiguity resolved, every rule backed by test cases. The group had invited Gruber to join by email in 2012 and never heard back. In September 2014 they shipped it as Standard Markdown.

The night it launched, an email from Gruber arrived, not about the spec but about the name, which he called “infuriating.” He made three requests: rename the project, shut down the domain without redirecting it, and apologize. They renamed it Common Markdown within a day. Not enough. Gruber followed up that no form of the word “Markdown” was acceptable. Two days after launch, the project became CommonMark. To this day, the most careful specification of Markdown ever written is not allowed to have Markdown in its name.

The name fight makes for good drama, but underneath it sat two genuinely different theories of how a format wins. Gruber thought loose conventions spread further than strict specs. The CommonMark camp thought a format used by millions across incompatible tools needs deterministic parsing. Both were right, in sequence: looseness won Markdown its adoption, and the mess that adoption created is exactly why CommonMark had to exist.

One more detail matters: CommonMark deliberately specified only the core. No tables, no task lists, no footnotes. It standardized parsing and left features to someone else.

GitHub picks the winner

That someone else was GitHub, mostly by accident.

GitHub’s key move wasn’t a spec. It was a product default. Put a README.md in your repo and GitHub renders it as your project’s front page. That one convention made Markdown mandatory for practically every developer. Nobody evaluated markup languages and chose Markdown; their project’s landing page simply was a Markdown file.

GitHub had been extending Markdown since about 2009 with things developers kept needing: tables, fenced code blocks, checkboxes, auto-linked issues. None of it was in Gruber’s spec. All of it became, in millions of heads, just “Markdown.”

Then in 2017 GitHub did the thing that settled the question: it published a formal GFM spec built directly on CommonMark, as a strict superset, and rebuilt its own parser on CommonMark’s reference implementation. The committee’s spec and the platform’s dialect became one lineage. CommonMark won the argument; GitHub supplied the enforcement. A spec with a test suite is nice. A spec sitting under 400+ million repositories is a standard.

And the mechanism still runs. When GitHub started rendering Mermaid diagrams in 2022, “Mermaid support” became table stakes across the whole ecosystem within a couple of years. Whatever GitHub renders, everyone else learns to render. Markdown does have a standards body after all. It just happens to be GitHub’s product team.

Where the flavors stand

Every flavor you’ll meet today is best understood by its distance from the CommonMark/GFM core:

Flavor	Relationship to the standard
CommonMark	The baseline spec
GFM	CommonMark + tables, task lists, strikethrough, autolinks. The de facto standard
GitLab Flavored Markdown	GFM + GitLab references, math, its own rendering pipeline
Obsidian, Typora	Near-GFM editor profiles with deliberately non-portable extras (wikilinks, callouts)
Pandoc, MultiMarkdown	Older publishing dialects that predate CommonMark and follow their own rules
MDX, MyST	Markdown as app infrastructure: components and ASTs, only loosely CommonMark-shaped

The practical rule falls straight out of the table: CommonMark is the floor, core GFM is the ceiling for anything that needs to travel between tools. Stay inside that ring (headings, links, images, fenced code, pipe tables, task lists) and your file renders correctly essentially everywhere. Step outside it and you’re targeting one specific tool, which is fine, as long as you’re doing it on purpose.

---

What exactly lives outside the ring (footnotes, math, diagrams, callouts, front matter, and which flavors support which) is its own topic, and a bigger one than it sounds. We’re covering it feature by feature in a follow-up post.