CommonMark

"A strongly defined, highly compatible specification of Markdown." Markdown shipped in 2004 as a Perl script and a page of prose, and the prose did not say what the script did. The reference implementation Markdown.pl was last updated in December 2004 and was itself buggy, so every later parser guessed differently and users "are often surprised to find that a document that renders one way on one system … renders differently on another." CommonMark is the attempt to replace the guessing with a grammar and a test suite.

Started in 2014 by John MacFarlane (Pandoc) with David Greenspan (Meteor), Vicent Marti (GitHub), Neil Williams (Reddit), Benjamin Dumke-von der Ehe (Stack Overflow) and Jeff Atwood (Discourse). Current leads are MacFarlane, Martin Woodward (GitHub) and Atwood. Adopted by Discourse, GitHub, GitLab, Reddit, Qt, Stack Overflow / Stack Exchange and Swift. The spec is CC BY-SA 4.0.

Where the ambiguity actually was

The spec ships its examples as machine-readable JSON, so the test suite can be counted rather than described. Version 0.31.2 contains 652 examples, and they are not spread evenly:

One fifth of the entire conformance suite is about * and _. Emphasis and links together take 222 of 652 examples, 34% of the spec's test surface — more than headings, lists, code blocks, block quotes and tables combined. Nothing about the format's reputation suggests that: Markdown is usually described as a simple syntax for headings and lists, and those are the parts that needed almost no disambiguation. The hard part was deciding what a run of asterisks means next to punctuation, inside a word, or nested in another run. A test suite is a map of where implementations disagreed, and this one says the disagreement lived almost entirely in inline text.

Ten years, still 0.x

The current spec is 0.31.2, released 28 January 2024, after 0.30 (June 2021), 0.29 (April 2019), 0.28 (August 2017), and a run back through 0.5 (October 2014). Twelve years of work, a version number that has never reached 1.0, and a two-year gap since the last release.

The homepage does not mention any of this. It says the spec "is quite robust after many years of public feedback" and names no version and no date anywhere on the page — a project whose entire purpose is to remove ambiguity about which behaviour you get, describing its own state in prose instead of a number. The fix is one line and the omission is the kind this spoke keeps finding in first-party pages.

The implementations

Six repositories under the commonmark GitHub organization (checked 2026-09-02):

cmark and commonmark.js were both pushed the day before this ingest, so the parsers are live even while the spec sits still. That is the split worth keeping: the standard is frozen and the implementations are not, which is the opposite of the arrangement protobuf-editions describes, where a frozen wire format is what makes yearly spec editions affordable. Here the spec is the frozen artifact and the code moves under it.

commonmark-spec carries the spec plus the C and JavaScript reference implementations; only commonmark-java declares a plain SPDX licence (BSD-2-Clause), the rest report NOASSERTION to the GitHub API, meaning a licence file GitHub could not classify rather than an absent one.

Why it belongs here

This spoke owns formats as infrastructure — protocol-buffers and its wire format, OpenAPI and its generators. CommonMark is the same shape: a specification, reference parsers in two languages, a conformance suite you can run, and a version history. What makes it unusual in that company is that the format already existed and was already universal before anyone specified it. Protobuf and OpenAPI were designed as specs; Markdown was retrofitted with one a decade after adoption, which is why the spec reads as an archaeology of existing implementations rather than a design.

The spec's own text was the obvious next pull, and it has been read: the emphasis section, the 20% of the suite counted above, is written up at commonmark-emphasis-rules — 17 numbered rules and three new defined terms replacing Gruber's two sentences. This page is still built from the homepage, the version index, the test JSON and the GitHub API, so it says what the suite covers; the grammar rules themselves live there. Still not fetched: the commonmark/help tutorial and talk.commonmark.org.

Related

commonmark-emphasis-rules · john-macfarlane · protocol-buffers · protobuf-editions · protobuf-wire-format · openapi-tools · developer-tooling

Cross-spoke. ../static-site-wiki named "the CommonMark or MDX specification" as growth edge 6 — generators are paged there and their input format was not. This page is that half. ../research-wiki runs on the other end: its lineage is machines operating over file-based markdown, and this is the grammar underneath that. Neither gets a duplicate page; link here.