CommonMark vs GFM: Key Differences

Markdown looks simple on the surface, but its lack of a formal specification led to years of inconsistent parsing. A heading might render correctly in one tool but break in another because each implementation made different choices about edge cases. CommonMark was created to solve this with a definitive spec. GitHub Flavored Markdown (GFM) builds on CommonMark with extensions for the needs of developer platforms. Understanding where they diverge helps you write Markdown that renders consistently wherever it appears.

What CommonMark Standardizes

CommonMark debuted in 2014 as an effort to eliminate ambiguity in Markdown parsing. John MacFarlane and contributors wrote a spec covering every edge case, backed by thousands of conformance tests. The result is the most rigorous Markdown specification available.

Key areas CommonMark clarifies include:

• Nested emphasis: Rules for how *foo **bar** baz* parses, preventing the mysterious broken bold/italic that plagued early parsers.
• List behavior: Precise rules for continuation, indentation, and when a list item can contain paragraphs or sub-lists.
• Link reference definitions: Exact scope and precedence rules for [ref]: url definitions.
• HTML blocks: Which HTML tags start a block-level HTML section and where those blocks end.
• Hard line breaks: Whether a trailing two spaces or \ produces a <br>, and in what contexts.

CommonMark does not include tables, task lists, strikethrough, or autolinks. These are everyday features for developers, which is exactly why GFM exists.

GFM Extensions on Top of CommonMark

GFM is a strict superset of CommonMark. Any valid CommonMark document is also valid GFM, but GFM adds several extensions:

Tables use pipe characters and hyphens:

| Feature    | CommonMark | GFM |
|------------|------------|-----|
| Tables     | No         | Yes |
| Task lists | No         | Yes |
| Strikethrough | No      | Yes |
| Autolinks  | No         | Yes |

Task lists add checkboxes to list items:

- [x] Write spec
- [ ] Implement parser
- [ ] Write tests

Strikethrough uses double tildes:

This is ~~deleted~~ text.

Autolinks turn bare URLs and email addresses into links without angle brackets:

Visit https://github.com for details.

Disallowed raw HTML is a security extension that filters certain HTML tags (like <script> and <textarea>) to prevent injection in user-generated content. This is not a syntax feature but a rendering restriction that CommonMark leaves to implementers.

Where They Diverge in Practice

Although GFM is a superset, there are subtle rendering differences that catch developers off guard:

Heading IDs: GFM automatically generates id attributes on headings for anchor linking. CommonMark makes no such requirement. If you rely on #heading-with-dashes anchors in your documentation, you are depending on GFM behavior.

Line breaks in lists: CommonMark and GFM handle hard line breaks inside list items slightly differently. A backslash at the end of a list line may produce a <br> in one but not the other depending on the surrounding whitespace.

Emphasis inside words: The spec rules for foo_bar_baz differ. CommonMark treats underscores within words as literal characters, while some older parsers emphasized them. GFM follows CommonMark rules strictly, but this remains a source of confusion when migrating from non-CommonMark parsers.

HTML block termination: CommonMark defines precise conditions for ending an HTML block — specifically, a blank line. GFM follows this, but tools like mdBook or Hugo sometimes apply their own HTML parsing rules, leading to different output.

Choosing Between Them

Use CommonMark when:

• You want maximum portability across Markdown renderers.
• You are building a parser and need a well-specified target.
• Your content does not need tables or task lists.

Use GFM when:

• You are writing for GitHub, GitLab, or npm (all use GFM).
• You need tables, task lists, or strikethrough in your documents.
• Your audience expects developer-friendly Markdown features.

Most modern documentation platforms — Docusaurus, MkDocs, Nuxt Content — support GFM by default. If you are writing READMEs, issue comments, or documentation hosted on GitHub, you are already writing GFM even if you did not realize it.

To verify how your Markdown renders under different specifications, try the live preview tool at /tools/markdown-to-html, which supports both CommonMark and GFM parsing modes so you can spot differences before publishing.