CommonMark vs GFM: 5 Differences and Platform Support

TL;DR — CommonMark vs GFM

• CommonMark is the standard Markdown spec. It defines only the core syntax — headings, lists, emphasis, links, images, code, and blockquotes — and deliberately leaves out extensions.
• GFM (GitHub Flavored Markdown) is a dialect that the GFM spec describes as a "strict superset" of CommonMark. It adds five extensions on top: tables, strikethrough, task lists, extended autolinks, and disallowed raw HTML.
• The GitHub.com features people associate with GitHub Markdown — alerts like [!NOTE], emoji shortcodes, @mentions, issue references, Mermaid diagrams, math, footnotes — are not in the GFM spec. They are a GitHub.com layer and generally do not work outside GitHub.
• Whether a single soft line break becomes a <br> is the same in CommonMark and the GFM spec: it does not. Only GitHub.com's issue/PR comment boxes turn one newline into a line break — .md files on GitHub still need two trailing spaces, a backslash, or a literal <br>.
• If you are not sure which dialect to write in: plain CommonMark is the most portable, GFM extensions are safe for GitHub-style platforms, and GitHub.com-only features should be treated as breakable elsewhere.
• FormatArc's Markdown to HTML converter supports the GFM extensions (tables, strikethrough, task lists, autolinks). You can also use it to check whether your Markdown depends on GFM-only syntax.

How CommonMark and GFM relate — GFM builds on CommonMark

CommonMark is the project that took the originally ambiguous Markdown grammar and re-specified it precisely, with a test suite. The goal is to remove implementation differences so any conformant parser produces the same output. As a spec it intentionally avoids extensions and only defines core constructs: headings, paragraphs, lists, links, images, emphasis, code, and blockquotes.

GFM (GitHub Flavored Markdown) is the Markdown dialect GitHub uses, and the GFM spec itself describes it as a "strict superset" of CommonMark. In spec terms that means:

• Any valid CommonMark document renders identically under a GFM parser.
• GFM only adds a handful of extensions to CommonMark; it does not change the core syntax.

The word "superset" applies to what the GFM spec defines. Once you factor in GitHub.com's actual rendering, individual library implementations, and the latest CommonMark revision, there are edge cases. This article keeps "extensions defined by the GFM spec" and "features GitHub.com adds on its own" separate.

Comparison table — CommonMark vs GFM

The key is the three columns. Tables, strikethrough, and the other GFM extensions work in any GFM-aware parser, not just on GitHub. Alerts, emoji, and footnotes are not in the GFM spec, so they are only guaranteed on GitHub.com (or platforms that copy it).

What actually changes when you convert to HTML

A CommonMark-only parser and a GFM-aware parser produce different HTML from the same Markdown. Compare this input:

| Product | Stock |
| --- | --- |
| Apple | 3 |

~~Sold out~~ — back in stock

- [x] Confirm restock
- [ ] Update price tags

A CommonMark-only parser leaves | Product | Stock | as a plain paragraph with literal pipes, keeps the ~~Sold out~~ tildes as text instead of <del>, and renders - [x] as an ordinary list item. A GFM-aware parser produces HTML with <table>, <del>, and <input type="checkbox">.

So when "Markdown looks broken," the cause is often a dialect mismatch between platforms. To check whether your Markdown depends on GFM extensions, paste it into Markdown to HTML and look at the output.

The 5 extensions GFM adds to CommonMark

Tables

Tables built from pipes | and hyphens -. CommonMark has no table syntax, so tables are a GFM extension. A CommonMark-only renderer leaves the pipes as text. For alignment markers (:--- / :---: / ---:), escaping pipes inside cells, and other details, see Markdown table syntax.

Strikethrough

~~text to strike~~ becomes a <del> element. Wrapping text in double tildes is a GFM extension and is not part of CommonMark.

Task lists

Start a list item with - [ ] (unchecked) or - [x] (checked) and it renders as a checkbox. On GitHub you can click the checkbox in an issue or PR body to toggle it, but that interactive behavior is a GitHub.com feature — a plain HTML renderer produces a static checkbox.

Extended autolinks

Write https://example.com directly and it becomes a link automatically. In CommonMark you have to wrap a URL in angle brackets (<https://example.com>), but GFM also detects bare URLs and links them.

Disallowed raw HTML

Both CommonMark and GFM allow you to embed raw HTML inside Markdown. The difference is that GFM disables a small set of tags — <script>, <iframe>, <style>, and a few others — as "disallowed raw HTML." On top of that, GitHub.com runs a separate, stricter sanitizer (stripping attributes and more). FormatArc's Markdown to HTML only does syntax conversion, so if you convert untrusted input, sanitize the output HTML separately.

Features that are GitHub.com, not the GFM spec

These are frequently presented as "GitHub Markdown" but are not in the GFM spec. Treat them as working only on GitHub.com (and a few services that imitate it).

• Alerts — > [!NOTE] / > [!TIP] / > [!IMPORTANT] / > [!WARNING] / > [!CAUTION]. They render as colored callouts.
• Emoji shortcodes — :smile:-style :name: syntax. Standard Markdown has no concept of emoji.
• @mentions / issue & PR references / commit SHAs — @username, #123, and commit hashes become links. These only make sense inside a repository context.
• Mermaid diagrams and math — ```mermaid code blocks and $...$ math. Another GitHub.com rendering-pipeline addition.
• Footnotes — [^1] syntax. GitHub.com supports them, but they are not part of the GFM spec. Some tools (like remark-gfm or Hugo's Goldmark) enable footnotes alongside the GFM-style extensions, but that is each implementation's choice.

Move Markdown that uses these into a non-GitHub context — a blog you pasted a README into, a docs tool — and it usually shows up as plain text. Treat them as GitHub.com-only syntax.

Line breaks (hard line break) work differently

This is a common point of confusion. In both CommonMark and the GFM spec, a single line break inside a paragraph (a soft line break) does not become a <br> — the lines join into one paragraph. To force a <br>, you put two trailing spaces, a trailing backslash \, or a literal <br> tag. That is identical in CommonMark and GFM.

The exception is GitHub.com's issue/PR/discussion comment boxes, which are configured to turn one newline straight into a <br>. On the same GitHub, .md files (READMEs, docs) follow standard CommonMark/GFM behavior and still need two spaces or \. "I got line breaks in a GitHub comment but not in my README" is exactly this.

Which platforms and tools use which dialect

More precisely: which of "plain CommonMark," "CommonMark + GFM extensions," or "their own dialect" each tool is closest to. A representative list:

"GFM support" does not necessarily mean the tool also supports GitHub.com's alerts or emoji. Conversely, a "CommonMark-only" tool can usually get the GFM extensions by adding a plugin. When in doubt, check the docs of the library or service you use for "which extensions are enabled."

How to check whether your environment supports GFM

You can get a rough answer without any deep investigation:

• Write a table (| col |), strikethrough (~~text~~), and a task list (- [ ]) and see whether each one renders. If they do, GFM extensions are on.
• If you use a library, check its config. marked needs gfm: true, remark needs the remark-gfm plugin, and markdown-it enables GFM tables and strikethrough by default.
• For static site generators, check the config file. Hugo has markup.goldmark.extensions, Astro has markdown.remarkPlugins (look for remark-gfm), and so on.

If you just want to know whether a particular Markdown file depends on GFM extensions, paste it into Markdown to HTML and see whether the tables and strikethrough turn into HTML.

Which dialect should you write in?

• Plain CommonMark is the most portable. It renders the way you intended in virtually every renderer.
• If you target GitHub or GitHub-like platforms (GitLab, most docs tools), the GFM extensions (tables, strikethrough, task lists, autolinks) are fine. That is the practical default.
• Alerts ([!NOTE] etc.), emoji shortcodes, @mentions, Mermaid, and footnotes should be used "on the assumption they break outside GitHub.com." Handy in a README, but paste it into a blog and it becomes plain text.
• If portability matters, avoid mixing in raw HTML. In both CommonMark and GFM, documents with raw HTML are subject to sanitization and renderer-specific behavior.

Which dialect does FormatArc's converter use?

FormatArc's Markdown to HTML runs marked with gfm: true internally. So:

• GFM spec extensions (tables, strikethrough, task lists, extended autolinks) convert straight to HTML.
• A soft line break inside a paragraph follows the breaks: false behavior — it does not become a <br>. Same as CommonMark/the GFM spec, and different from GitHub.com's comment-box behavior.
• GitHub.com-only features — alerts like [!NOTE], emoji shortcodes, @mentions, Mermaid, footnotes — are not supported, because they are not part of the GFM spec.

The reverse tool, HTML to Markdown, outputs GFM-ish Markdown that includes tables and strikethrough. Both run entirely in the browser with no sign-up and no upload, so pasting an unpublished internal document does not send it anywhere.

For step-by-step conversion guides, see How to convert Markdown to HTML and, for the reverse, How to convert HTML to Markdown.

Frequently asked questions

Should I write Markdown in CommonMark or GFM?

Plain CommonMark is the most portable. If you target GitHub or GitHub-like platforms, the GFM extensions (tables, strikethrough, task lists, autolinks) are fine. Use GitHub.com-only features like [!NOTE] on the assumption they break outside GitHub.

Does CommonMark have table syntax?

No. Tables are a GFM extension and are not in the CommonMark spec. A CommonMark-only renderer shows | col | as plain text with literal pipes. For details on writing tables, see Markdown table syntax.

Do GitHub's [!NOTE] alerts work in other tools?

Generally only on GitHub.com (and a few services that imitate it). The GFM spec has no alert syntax, so other renderers show > [!NOTE] as text inside a blockquote.

Are Obsidian and Notion GFM-compatible?

Not fully. Obsidian is CommonMark-based, supports GFM tables and task lists, and adds its own syntax like [[wikilinks]]. Notion has its own dialect; its Markdown export is GFM-ish, but the in-editor syntax is Notion-specific. Check each tool's docs for supported syntax.

Which dialect does FormatArc convert with?

GFM-ish. Markdown to HTML runs marked with gfm: true, so it supports tables, strikethrough, task lists, and autolinks. Soft line breaks do not become <br> (same as CommonMark/the GFM spec). GitHub.com-only features — alerts, emoji, mentions, Mermaid, footnotes — are not supported.

Related articles

• How to convert Markdown to HTML — the concrete steps for converting Markdown to HTML, including GFM tables and task lists.
• Markdown table syntax: alignment, escaping, copy-paste examples — GFM table alignment, escaping pipes, and handling line breaks in detail.
• GFM table cheatsheet — one-page reference for alignment, escaped pipes, and rendered output across GitHub / GitLab / Obsidian / Notion.
• How to convert HTML to Markdown — converting HTML from web pages or Notion exports into GFM-ish Markdown.

Summary

CommonMark is the standard Markdown spec; GFM is a dialect that builds on it with five extensions (tables, strikethrough, task lists, extended autolinks, disallowed raw HTML). The alerts, emoji, @mentions, Mermaid, and footnotes you see on GitHub.com sit on yet another layer — GitHub.com's own — and generally do not work outside GitHub.

If you are unsure which dialect to write in: CommonMark for maximum portability, GFM extensions for GitHub-style platforms, and GitHub.com-only features on the assumption they break elsewhere. When you want to check whether your Markdown depends on GFM extensions, or just convert Markdown to HTML, use Markdown to HTML — it runs entirely in the browser with no sign-up and no upload.