What is the CommonMark Specification?

CommonMark is the definitive standard specification for the Markdown document syntax. It was designed to resolve a decade of fragmentation, edge-case ambiguities, and parsing inconsistencies that arose from John Gruber’s original 2004 Markdown implementation.

When Gruber released Markdown, he provided an informal syntax description and a Perl script (Markdown.pl). Because the specification lacked formal grammar definitions, developers who reimplemented Markdown in Python, Ruby, C, and JavaScript encountered hundreds of edge cases: How should four spaces inside a blockquote be parsed? How do nested ordered lists interact with indented code blocks? Different parsers produced contradictory HTML output.

The birth of CommonMark

In 2014, a group of prominent software engineers—including John MacFarlane, Jeff Atwood, Neil Vermeulen, and David Greenspan—collaborated to create CommonMark.

The project achieved three critical breakthroughs:

1. A rigorous specification: A 600+ page document specifying exact parsing behavior for every conceivable syntax combination.
2. A comprehensive test suite: Over 650 executable test cases verifying edge cases, tab expansions, and HTML entity handling.
3. Reference implementations: Ultra-fast, battle-tested reference implementations in C (cmark) and JavaScript (commonmark.js).

Key parsing ambiguities resolved by CommonMark

CommonMark eliminated major ambiguities that previously plagued Markdown documents:

1. Tight vs loose lists

CommonMark formally defined the difference between tight lists (no <p> wrapper) and loose lists (wrapped in <p> elements) based on whether blank lines separate items:

<!-- Tight list: renders compact HTML <li> items -->
- First item
- Second item

<!-- Loose list: renders expanded <li><p> items -->
- First item

- Second item

2. Nested blockquote handling

CommonMark established deterministic rules for combining blockquotes with lists and headers, ensuring that nested formatting never breaks document flow.

CommonMark in Oyma

Oyma uses CommonMark as its foundational parsing layer on macOS. Whether you write technical documentation, executive meeting summaries, or daily journals, Oyma ensures that your syntax renders deterministically. Documents authored in Oyma conform perfectly to standard compilers across the web.