CommonMark is a precise, machine-testable specification of the Markdown syntax, maintained at spec.commonmark.org and authored principally by John MacFarlane. It exists to solve a problem created by Markdown’s own success: John Gruber’s original 2004 description was written as informal prose and left many cases undefined, so the dozens of independent implementations that sprang up disagreed about how to render the same input. CommonMark replaces that ambiguity with a single, carefully worded standard.
The specification is unusual in that it ships with an extensive battery of test cases. Each version of the spec is published alongside a JSON file of input-and-expected-output examples, so any implementation can be checked for conformance automatically. This shifts Markdown from a loose convention into something an implementer can target exactly, with a clear definition of what the right answer is for tricky inputs such as nested emphasis, mixed lists, and HTML blocks.
CommonMark is versioned rather than frozen, reflecting the difficulty of nailing down every corner of Markdown’s behavior. The spec page lists a sequence of releases beginning with 0.5 in October 2014 and continuing through later revisions, including 0.28 (2017), 0.29 (2019), 0.30 (2021), and 0.31.2 (2024). Each version carries a documented changelog and its own set of test cases, so implementations can state precisely which spec version they support.
The specification text itself is distributed under a Creative Commons Attribution-ShareAlike 4.0 International License, and the project provides supporting resources including a discussion forum, a reference repository, and an interactive testing tool nicknamed the “dingus” that renders arbitrary input according to the spec. These tools let authors and implementers see exactly how the standard treats any given snippet.
CommonMark became the foundation for many widely used Markdown engines and the base layer for extended flavors that add tables, task lists, and other features on top of the strict core. By giving Markdown a real specification with conformance tests, CommonMark turned a popular but fuzzy convention into an interoperable standard, allowing tools to agree on rendering while still leaving room for documented extensions.