CommonMark vs GitHub Flavored Markdown: what is the difference?

Dark navy cover card with the title 'CommonMark vs GitHub Flavored Markdown: what is the difference?' in white and a green accent bar

CommonMark is a strict, testable specification of core Markdown, and GitHub Flavored Markdown (GFM) is CommonMark plus a set of extensions. In the CommonMark vs GitHub Flavored Markdown question, the difference comes down to five additions in the GFM spec: tables, task lists, strikethrough, extended autolinks and a filter for a few dangerous HTML tags. Anything valid in CommonMark is valid in GFM.

What is CommonMark?

CommonMark is an unambiguous specification of Markdown with a test suite, written because the original Markdown description left too much open. The CommonMark site says John Gruber's canonical description "does not specify the syntax unambiguously", and that Markdown.pl was buggy and last updated December 17th, 2004.

Without a spec, implementations drifted apart. CommonMark's own example: a document that renders one way on a GitHub wiki renders differently when converted with Pandoc, and since nothing in Markdown counts as a syntax error, nobody notices right away. The latest spec version is 0.31.2, dated 2024-01-28.

Tables, task lists and strikethrough are not in it, on purpose.

What is GitHub Flavored Markdown?

GitHub Flavored Markdown is the Markdown dialect GitHub supports for user content, defined as CommonMark plus marked extensions. The GFM spec calls GFM "a strict superset of CommonMark" and labels every feature that isn't in CommonMark as an extension.

GitHub's 2017 engineering post explains the history. GFM first ran on a parser called Sundown. GitHub then moved to a backend based on cmark, the CommonMark reference implementation, and keeps its extensions in a fork of cmark. GitHub measured that less than 1% of existing user content would be affected by the switch.

CommonMark vs GitHub Flavored Markdown, feature by feature

The difference between CommonMark and GitHub Flavored Markdown is the list of extension sections in the GFM spec. Everything else is shared.

Feature CommonMark GFM GFM syntax
Headings, lists, links, code, emphasis Yes Yes Same in both
Tables No Yes Pipe rows with a --- delimiter row
Task list items No Yes - [ ] and - [x]
Strikethrough No Yes ~~text~~ (one or two tildes)
Autolinks Only inside < and > Also bare www. and URLs www.example.com
Raw HTML Passed through Nine tags filtered <script> becomes &lt;script>

Autolinks

Autolinks are the difference you'll hit first. The CommonMark spec defines autolinks as "absolute URIs and email addresses inside < and >". So <https://example.com> is a link in both, but a bare www.example.com only becomes a link in GFM, which recognises a www. followed by a valid domain.

Tables and task lists

GFM tables need a header row and a delimiter row with the same number of cells, or no table is recognized. If yours show up as raw pipes, our guide to why Markdown tables don't render walks through each cause. Task list items start with [ ] or [x] and render as checkboxes, where a space inside the brackets means unchecked.

Strikethrough

Strikethrough wraps text in one or two tildes. Three or more tildes don't count, so ~~~ won't strike anything through.

Disallowed raw HTML

GFM's tagfilter extension blocks nine tags: <title>, <textarea>, <style>, <xmp>, <iframe>, <noembed>, <noframes>, <script> and <plaintext>. It replaces the leading < with &lt; and leaves every other tag alone. CommonMark has no such filter. That's not a full sanitizer, and the GFM spec itself notes that GitHub does extra post-processing and sanitization after converting to HTML. If you render user Markdown on your own site, see how to display Markdown in HTML for the sanitizing step.

GitHub features that aren't in the GFM spec

Some Markdown that works on GitHub isn't defined in the GFM spec at all. The GFM spec is still at version 0.29-gfm from 2019-04-06, while CommonMark has moved on to 0.31.2.

Two examples from GitHub's own docs:

  • Footnotes use [^1] syntax and render at the bottom of the document. GitHub notes that footnotes are not supported in wikis.
  • Alerts, also called callouts or admonitions, are described as "a Markdown extension based on the blockquote syntax".

Neither appears among the spec's extension sections. Libraries decide for themselves: remark-gfm includes footnotes in its GFM support. Its authors also warn that in several edge cases GitHub's implementation works differently than described in the spec.

Which one should you write for?

Write for the parser that will render your Markdown, not for the name on the spec:

Where the Markdown ends up Write for
GitHub READMEs, issues, pull requests GFM, plus GitHub extras like footnotes
A site built with remark plus remark-gfm, or marked with defaults GFM (marked's gfm option defaults to true)
A strict CommonMark parser, or content you'll move between tools CommonMark only

My take: write CommonMark by default and reach for GFM features only when you know the target renders them. A table or task list in a portable document is a bet on the next tool. Core CommonMark is the part every modern parser agrees on.

The limitation: GitHub itself moves. It adds features like alerts outside the spec, so "GFM" in a library's docs may not match what github.com renders today. Test on the real destination.

One more caveat from our side: OnlineViewer's Markdown preview uses a small built-in renderer, not a full CommonMark or GFM parser. It handles headings, emphasis, code, links, images, blockquotes, lists, horizontal rules and paragraphs, so it can't tell you how a strict parser treats an edge case. If you also hand-write config files, the same "spec vs dialect" problem shows up in JSON vs JSON5 vs JSONC.

FAQ

Is GitHub Flavored Markdown the same as CommonMark?

No. GFM is a strict superset of CommonMark: every CommonMark feature works in GFM, and GFM adds extensions such as tables, task lists, strikethrough, extended autolinks and an HTML tag filter.

Does CommonMark support tables?

Not in the core spec. Tables are one of the extensions the GFM spec adds on top of CommonMark, so a strict CommonMark parser prints table syntax as plain text.

Are footnotes part of GitHub Flavored Markdown?

GitHub supports footnotes with [^1] syntax, but the GFM spec (version 0.29-gfm) doesn't define them. Some libraries, such as remark-gfm, include footnotes in their GFM support anyway.

Will a CommonMark document render the same on GitHub?

Almost always, since GFM is a superset. The main surprises are bare URLs becoming links, tildes turning into strikethrough, and a few HTML tags such as script and iframe being filtered.

Sources