CommonMark is a formal specification for markdown syntax, published in 2014. It defines exactly how every markdown construct should be parsed and rendered, resolving hundreds of ambiguities in John Gruber’s original 2004 description. Most modern markdown tools, including GitHub, VS Code, and MDtoLink, build on CommonMark as their foundation.

Why CommonMark Exists

The original markdown specification was a blog post by John Gruber. It described the syntax in prose but left many edge cases undefined:

What happens when you nest a blockquote inside a list?
Does a blank line between list items change the HTML output?
How do you handle overlapping emphasis markers like *foo **bar* baz**?
Should a link inside another link be valid?

Different markdown processors answered these questions differently. A document that rendered one way in one tool looked different in another. There was no way to test whether a parser was “correct” because there was no authoritative definition of correct.

In 2012, Jeff Atwood (Stack Overflow co-founder), John MacFarlane (Pandoc author), and others started work on a unified specification. The result, published in 2014, was CommonMark.

What CommonMark Standardizes

The specification covers 17 categories of syntax with 652 test cases (as of spec version 0.31.2):

Category	What It Defines
Thematic breaks	`---`, `***`, `___` rules
ATX headings	`#` through `######`
Setext headings	`===` and `---` underlines
Indented code blocks	4-space indent rules
Fenced code blocks	Backtick and tilde fences
Paragraphs	When lines merge, when they separate
Blank lines	Their effect on surrounding elements
Block quotes	`>` nesting and continuation
List items	Indentation, lazy continuation, loose vs tight
Lists	Ordered/unordered, start numbers
Backslash escapes	Which characters can be escaped
Entity references	HTML entity handling
Code spans	Backtick matching rules
Emphasis	`*` and `_` precedence and nesting
Links	Inline, reference, and autolinks
Images	`![]()` parsing
Raw HTML	When HTML passes through vs gets escaped

Each category has precise rules with examples showing input and expected output.

CommonMark vs Original Markdown

Aspect	Original Markdown (2004)	CommonMark (2014+)
Format	Blog post / informal description	Formal spec with test suite
Edge cases	Undefined	Defined (652+ tests)
Reference implementation	Markdown.pl (Perl)	cmark (C), commonmark.js (JS)
Ambiguity	Many	None by design
Extensions	Not addressed	Not included (handled by flavors)
Maintained by	John Gruber	CommonMark team (John MacFarlane et al.)

CommonMark is intentionally conservative. It specifies only the core markdown syntax and leaves extensions (tables, task lists, strikethrough) to flavors like GFM.

CommonMark vs GFM

GitHub Flavored Markdown (GFM) is built on top of CommonMark. Everything in CommonMark is valid GFM. GFM adds features that CommonMark does not include:

Feature	CommonMark	GFM
Headings	Yes	Yes
Emphasis (bold/italic)	Yes	Yes
Links and images	Yes	Yes
Code blocks	Yes	Yes
Lists	Yes	Yes
Blockquotes	Yes	Yes
Tables	No	Yes
Task lists	No	Yes
Strikethrough	No	Yes
Auto-linking bare URLs	No	Yes
Footnotes	No	Yes
Disallowed raw HTML	No	Yes (security filtering)

For most writing, GFM is the practical choice because tables and task lists are used frequently. CommonMark is the right reference when building a parser or when you need to understand how the core syntax works.

See What Is GitHub Flavored Markdown? for the full breakdown.

Who Uses CommonMark

Tool / Platform	CommonMark-Based?
GitHub (GFM)	Yes (superset)
GitLab (GLFM)	Yes (superset)
VS Code	Yes
Discourse	Yes
Swift Playgrounds	Yes
Reddit (new editor)	Yes
Stack Overflow	Yes (CommonMark since 2020)
Pandoc	Supports CommonMark mode
MDtoLink	Yes

The cmark reference implementation (written in C) and commonmark.js (JavaScript) are the official parsers. Many other parsers (marked, markdown-it, pulldown-cmark) implement CommonMark or a close variant.

The CommonMark Spec in Practice

Here is an example of an ambiguity that CommonMark resolves:

What does this produce?

- foo

  bar

In the original markdown, different parsers disagreed: is bar a continuation of the list item, or a separate paragraph? CommonMark defines it precisely: bar is a continuation of the list item because it is indented to the content column of the item.

Another example: overlapping emphasis.

*foo **bar* baz**

Some old parsers would crash or produce inconsistent output. CommonMark has rules for how emphasis delimiters match, and this produces: <em>foo <strong>bar</strong></em> baz** (the last ** is literal because it has no matching opener after the * closes).

FAQ

Is CommonMark the “official” markdown standard?

It is the closest thing to an official standard. John Gruber (the original creator) never endorsed it, but the specification has been adopted by GitHub, GitLab, Stack Overflow, Reddit, and most major platforms.

Should I write CommonMark or GFM?

Write GFM if you use tables, task lists, or strikethrough. GFM includes all of CommonMark plus those extensions. If you only use core syntax (headings, emphasis, links, lists, code), your document is valid CommonMark and GFM simultaneously.

Does CommonMark support tables?

No. Tables are a GFM extension, not part of the CommonMark specification. CommonMark covers only the core syntax.

Where can I read the full specification?

The specification is at spec.commonmark.org. It includes every parsing rule with input/output examples. The CommonMark dingus lets you test how any input parses under the spec.

Try It Out

Write CommonMark-compatible markdown in the MDtoLink editor and see it render in real time. Publish to a shareable URL when you’re done.

For the full syntax, see the markdown cheat sheet. For the GFM extensions, see What Is GitHub Flavored Markdown?.

What Is CommonMark? The Standardized Markdown Spec