CommonMark versus GitHub Flavored Markdown, and where the line sits

Three names get used interchangeably for Markdown, and they are not the same thing. Markdown is the original 2004 format. CommonMark is the formal specification that pinned down what Markdown was supposed to mean. GitHub Flavored Markdown is CommonMark plus a set of extensions GitHub added. Any file that renders correctly everywhere needs the third, because the first two do not include tables or task lists.

The practical difference shows up in a single line. A pipe-delimited table is a GFM feature. Feed it to a strict CommonMark parser and the pipes come back as literal text, not a table. That is not a bug in either implementation; it is the boundary between the two specifications, and knowing where it sits tells you which renderer to reach for.

Key Takeaways

• CommonMark is the base specification, version 0.31.2, with over 600 conformance test cases.
• GFM is a strict superset: it keeps every CommonMark rule and adds tables, task lists, strikethrough, autolinks, and disallowed raw HTML.
• GFM support implies CommonMark support, so supporting GFM is the safer choice.
• A file using GFM extensions will render as literal text in a strict CommonMark renderer, not as an error.

What Is CommonMark?

CommonMark is a specification for Markdown, written to resolve the ambiguity that made the original format unreliable across parsers. Markdown was created in 2004 by John Gruber with the goal of readable plain text, and it succeeded well enough that dozens of parsers implemented it slightly differently. The same document could render differently depending on which tool processed it.

The CommonMark specification fixed that by defining an unambiguous grammar backed by a conformance test suite of more than 600 cases, each pairing input with expected output. The current release is version 0.31.2, dated 2024-01-28, maintained by John MacFarlane. When a project claims CommonMark support, the meaningful version of that claim is whether it passes those tests.

CommonMark is the baseline that modern renderers build on. GitHub, GitLab, Reddit, and most contemporary documentation tools parse it as their foundation rather than as an alternative to their own extensions. The CommonMark project site explains the intent behind the specification, and the Markdown syntax cheat sheet covers the base constructs it defines.

What Is GitHub Flavored Markdown?

GitHub Flavored Markdown, or GFM, is an extension of CommonMark. Its specification, version 0.29-gfm, describes itself as a strict superset: every CommonMark construct still behaves identically, and the additions sit on top.

The additions are the practical reason most people use GFM without knowing the name exists. The GitHub Flavored Markdown specification documents each one against a stated difference from CommonMark. They are tables, task list items, strikethrough, extended autolinks, and a documented policy for disallowed raw HTML. Each one solves a case that plain CommonMark handles badly or not at all.

Feature	CommonMark	GFM
Headings, lists, links, code	Yes	Yes
Pipe tables	No	Yes
Task list checkboxes	No	Yes
~~strikethrough~~	No	Yes
Bare URL autolinks	No	Yes
Raw HTML passthrough	Yes	Documented

Read that table as a subset relation rather than a comparison of rivals. Everything in the CommonMark column is also true in the GFM column, and the reverse is not the case.

Where the two actually diverge

The difference is easiest to see by taking a construct GFM adds and running it through a strict CommonMark parser.

A GFM table:

| Tool | Runs locally |
| --- | --- |
| Converter | Yes |

In a GFM renderer this becomes a real table. In a strict CommonMark renderer, the leading pipe makes the line a paragraph, and every pipe character appears literally in the output. Nothing errors. The document renders, just not the way its author intended.

A GFM task list behaves the same way:

- [x] shipped
- [ ] pending

A CommonMark parser produces a plain unordered list whose items begin with the literal text [x] and [ ]. The structure is preserved, the semantics are not.

This is the failure mode worth remembering. Because CommonMark has no concept of either construct, a strict parser does not reject the file. It renders it as text. A document that looks broken is usually a dialect mismatch rather than a syntax error, and the fix is to switch renderers rather than to hunt for a missing character.

Which one should you target?

Target GFM unless you have a specific reason not to. The reasoning is a subset argument rather than a quality judgment: a GFM parser handles every CommonMark construct, so supporting GFM costs nothing in compatibility and buys the extensions. A CommonMark-only parser handles the narrower set and will render extension syntax as literal text.

There are two situations where targeting plain CommonMark makes sense. One is a system that must accept Markdown from untrusted sources and wants the smallest feature surface, accepting that some documents will lose their tables. The other is long-term archival storage, where depending on an extension set is a liability and the base specification is the more stable contract. Neither applies to a documentation site, which is why GFM dominates in practice. The first is a system that must accept Markdown from untrusted sources and wants the smallest possible feature surface, accepting that some documents will lose their tables. The second is archival or long-term storage, where depending on an extension set is a liability and the base specification is the more stable contract.

If you are choosing a converter rather than writing one, ask whether it claims GFM support and whether it has a test suite. Claiming support is easy; the GitHub documentation on Markdown shows what the extensions do in practice, and a converter with a conformance suite is one that has actually been checked against the specification.

A note on the third name

"Markdown" on its own is the vaguest of the three labels. It can mean Gruber's original design, the CommonMark specification, GFM, or whatever a particular tool happens to implement. When documentation says "written in Markdown" without naming a dialect, the safe assumption is that it means the common denominator, which is CommonMark plus whatever extensions its readers' tools happen to support. The Markdown specification history records the original design intent that later specifications were written to preserve.

The Python-Markdown documentation reflects this directly, documenting its own dialect behaviour rather than claiming a single universal answer. This ambiguity is the reason the original format needed a specification in the first place. A name that four different groups define differently is not a specification, and the practical fix has been to name the dialect whenever precision matters.

Related tools and further reading

The Markdown syntax cheat sheet covers the core CommonMark constructs with the HTML each produces, and marks which ones are GFM additions. The Markdown to HTML converter parses CommonMark as its base and layers GFM on top, so the same file renders predictably across platforms. If you are weighing the formats themselves, Markdown vs HTML covers when each fits. For the security consequence of GFM's raw HTML passthrough, sanitizing Markdown output against XSS covers why the output still needs a sanitizer.