How Markdown Got a Spec: From Daring Fireball to CommonMark

Markdown got its spec in pieces, and late. John Gruber released it in 2004 as a Perl script with a prose description, and a group of engineers began writing a real specification a decade later. That effort became CommonMark after a public naming dispute.

2004: a Perl script and a readable syntax

Markdown came from John Gruber, who published it on Daring Fireball. His project page calls it "a text-to-HTML conversion tool for web writers." It was two things at once: a plain-text syntax and a Perl script, Markdown.pl, that converted that syntax to HTML. The version 1.0.1 release on the page is dated 17 December 2004, under a BSD-style license.

The stated goal was readability. In Gruber's words, "the overriding design goal for Markdown's formatting syntax is to make it as readable as possible." A document should work as plain text without looking like it is full of tags, and the syntax borrows heavily from plain-text email.

That goal explains why Markdown spread. It doesn't make Markdown a specification. What shipped was a prose description and one implementation.

Why a readable syntax left gaps

Prose leaves questions open. The CommonMark spec says Gruber's description "does not specify the syntax unambiguously," and lists 14 questions it leaves unanswered. Take this one:

- parent
  - child

How many spaces does a sublist need? Does a block quote need a blank line before it? Which wins when a list marker and emphasis collide? The original text doesn't say.

Implementers went to Markdown.pl for answers, but the spec describes it as "quite buggy." Copy a buggy reference and you inherit its bugs. Rewrite from the prose and you ship your own guesses.

Markdown also has no syntax errors, so nothing fails loudly. As the spec puts it, "the divergence often isn't discovered right away." That is why the same file renders differently across parsers.

A crowd of flavors

While the gaps stayed open, implementations grew their own features. Tables, footnotes and definition lists arrived in different forms in different tools, and GitHub ran its own variant. Footnotes still differ between GFM and Pandoc, so check which syntax your target renderer supports.

Gruber didn't push for one standard. Wikipedia quotes a September 2014 tweet of his arguing that different sites and people have different needs. What emerged was a family of dialects: one ancestor, no shared rulebook.

The 2014 naming dispute

People who ran Markdown at scale decided to write the rulebook anyway. CommonMark's site lists the 2014 group: John MacFarlane (Pandoc), David Greenspan (Meteor), Vicent Marti (GitHub), Neil Williams (Reddit), Benjamin Dumke-von der Ehe (Stack Overflow) and Jeff Atwood (Discourse).

They first called it Standard Markdown. Atwood's account of the aftermath, dated 4 September 2014, runs like this:

• In November 2012 the team invited Gruber to join. He never replied.
• On 19 August 2014 they sent him the spec. After two weeks of silence they assumed he was fine with the project and its name.
• Gruber then called the name "infuriating." He asked them to rename it, shut down standardmarkdown.com without a redirect, and apologize.
• Atwood apologized and renamed the project Common Markdown.
• Gruber later said no form of the word "Markdown" was acceptable, so it became CommonMark.

Both sides had a point. Gruber made Markdown and owned its name. The group wanted a standard people could build on. The compromise kept his project's name off the spec.

What a spec changed

The spec's examples are the real product. Each one is a snippet of Markdown paired with the exact HTML it must produce, so they double as conformance tests. Version 0.31.2, dated 28 January 2024, runs to Example 652. A parser author can run the whole list and see exactly where their parser differs.

Standards bodies followed. Per Wikipedia, RFC 7763 introduced the text/markdown media type in March 2016, and RFC 7764 registered variants such as MultiMarkdown, GitHub Flavored Markdown, Pandoc and Markdown Extra. On 14 March 2017 GitHub published a formal GFM spec, a strict superset of CommonMark that adds tables, strikethrough, autolinks and task lists. GFM autolinks are one of those additions.

CommonMark lists Discourse, GitHub, GitLab, Reddit, Qt, Stack Overflow and Swift among its adopters. It has still not reached 1.0; the latest release is 0.31.2.

When to rely on it (and when to skip it)

Stick to CommonMark constructs and your file should behave the same in most modern renderers. Reach for extensions like tables or footnotes and you're back to checking the target. Markdown remains a poor fit for complex layout, and a spec does not change that.

How Carets fits in

Markdown is plain text, so your notes outlast any one renderer. Carets is a fast, native notes and code editor for iPhone, iPad and Mac. It handles Markdown, plain text and code with syntax highlighting in one editor, and organizes it all into files, projects and tags. Your files stay plain text, so they stay portable whichever flavor you write.

Get Carets on the App Store for iPhone, iPad and Mac.

Frequently Asked Questions

Who created Markdown?

John Gruber created Markdown in 2004 as a Perl script plus a plain-text syntax. Aaron Swartz acted as a sounding board. The last release of the original, version 1.0.1, is dated 17 December 2004.

Why was CommonMark not called Standard Markdown?

The project launched as Standard Markdown, but Gruber objected to the name in September 2014. It became Common Markdown briefly, then CommonMark after he said no form of the word Markdown was acceptable.

Is CommonMark version 1.0 yet?

No. The latest spec is 0.31.2, dated 28 January 2024. Its numbered examples, 652 in that version, double as conformance tests.

Is GitHub Flavored Markdown the same as CommonMark?

No. GFM is a strict superset of CommonMark. GitHub published its formal spec in March 2017, adding tables, strikethrough, autolinks and task lists.