toolhq.io

All posts
4 min readby Jameel Haider

CommonMark vs GitHub Flavored Markdown

You write a table in a README, it renders perfectly on GitHub, then looks like plain text in another tool. Markdown feels universal, but it was never one specification. The difference between CommonMark and GitHub Flavored Markdown explains most of the inconsistencies you run into.

CommonMark is the strict spec

The original Markdown from 2004 was a loose description with many ambiguous cases, so different implementations guessed differently. CommonMark was created to fix that: a precise, testable specification that says exactly how every construct should parse, down to edge cases like nested lists and how many spaces start a code block. It covers the core syntax everyone knows: headings, emphasis, links, images, blockquotes, lists, and fenced code blocks.

What CommonMark deliberately leaves out is anything beyond that core. It has no tables, no strikethrough, no task lists. It is a foundation other dialects build on rather than a full feature set.

GitHub Flavored Markdown adds extensions

GitHub Flavored Markdown, usually written GFM, is CommonMark plus a defined set of extensions. Everything that parses under CommonMark parses the same way under GFM, so GFM is a strict superset. The additions are the features you probably use daily:

  • Tables, built with pipes and a header separator row.
  • Task lists, the - [ ] and - [x] checkboxes.
  • Strikethrough with ~~text~~.
  • Autolinks, turning a bare URL like https://example.com into a link without angle brackets.
| Feature     | CommonMark | GFM |
|-------------|------------|-----|
| Tables      | no         | yes |
| Task lists  | no         | yes |
| Autolinks   | no         | yes |

- [x] write the spec
- [ ] ship it

Paste that into a CommonMark-only renderer and the table becomes literal pipe characters and the checkboxes stay as text.

Why renderers disagree

Most Markdown you meet is some dialect between these two, and a few tools add their own extras on top of GFM, such as footnotes, definition lists, or math. When your document looks wrong somewhere, the usual cause is one of three things:

  • The renderer is CommonMark-only and does not know GFM extensions.
  • The renderer follows a different, pre-CommonMark dialect with its own quirks.
  • The renderer added nonstandard features your source does not use, so nothing matches.

The practical defense is to know which dialect your target uses. GitHub, GitLab, and many static site generators speak GFM. Comment boxes and chat tools are often more limited. If a document must render identically everywhere, stay within plain CommonMark and avoid tables and task lists.

Preview before you publish

The quickest way to catch a dialect problem is to preview your Markdown as it will actually render. The Markdown preview tool shows the formatted output live as you type, entirely in your browser so your draft never leaves your device. For a syntax refresher, keep Markdown to HTML reference handy.

The takeaway: CommonMark is the strict base, GFM is that base plus tables, task lists, strikethrough, and autolinks, and most rendering surprises come from a tool speaking a different dialect than the one you wrote for.