Markdown Flavors: GFM vs CommonMark

By the end of this lesson you'll know why the same Markdown can render differently in different tools — and how to tell core CommonMark apart from GitHub Flavored Markdown so you can write documents that stay portable.

Learn Markdown Flavors: GFM vs CommonMark in our free Markdown course — an interactive lesson with worked examples, a practice exercise and a quick reference.

Part of the free Markdown course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

Markdown flavors are like dialects of one language . Everyone agrees on the core vocabulary — headings, bold, lists — so a sentence in that core is understood everywhere. But each region added its own slang: GitHub says "tables and checkboxes", Pandoc says "footnotes and citations". You're still speaking Markdown, but a phrase from one dialect may get blank looks somewhere else. Writing portably means sticking to the shared vocabulary so no audience is left confused.

1. The Original and CommonMark

Markdown was created by John Gruber in 2004 (with help from Aaron Swartz) as a simple way to write formatted text. The original description was deliberately informal, which left many edge cases undefined — so different tools interpreted them differently. CommonMark arrived later as a strict specification : a precise, testable definition of how Markdown should behave, so the same input gives the same output across compliant tools.

2. GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown is defined as a strict superset of CommonMark — it includes everything CommonMark does and adds popular extensions on top: tables , task lists ( - [ ] ), strikethrough ( ~~text~~ ), autolinks (bare URLs become clickable), and fenced code with language highlighting. These are wildly useful but not part of the core spec, so they may not render on a plain CommonMark viewer.

Fill in the blanks so the program prints Markdown using only the common core — a heading and a bullet list. None of it should depend on a specific flavor.

3. Why Flavors Diverged

The original Markdown was a description, not a rigorous standard, so it left questions unanswered: how many spaces nest a list? What happens with overlapping emphasis? Each implementation answered differently, and many added new features their users wanted — tables, footnotes, math. The result is a family of flavors : CommonMark (the unifying spec), GFM (CommonMark plus GitHub's extras), MultiMarkdown (footnotes, tables, metadata, citations), and Pandoc Markdown (a very extensible variant aimed at document conversion).

Here's a worked example that prints Markdown source and labels the flavor each line needs. Run it, read the comments, then paste the core block and the GFM block into different viewers to see which lines render.

Fill in the blanks so the program prints a strikethrough price change. Remember: ~~text~~ is a GFM extension, so it may not render on a core-only viewer.

4. Writing Portable Markdown

To make a document render the same everywhere, lean on the shared core : headings, paragraphs, emphasis, lists, links, images, blockquotes, and fenced code. These are defined by CommonMark and supported almost universally. Reach for flavor-specific syntax (GFM tables, task lists, math) only when you know your audience's platform supports it — or provide a plain-core fallback.

No blanks this time — just a brief and an outline. Use console.log to print a short note using only core CommonMark (heading, emphasis, list, link), then add one clearly-commented GFM-only line and note that it needs a GFM processor.

Q: Is GFM a totally separate language from CommonMark?

No. GFM is a strict superset of CommonMark — it adds features but keeps full compatibility, so any CommonMark document is also valid GFM.

The core, as defined by CommonMark. Once that's solid, GFM's additions (tables, task lists, strikethrough) are small and easy to layer on.

Q: Why does my Markdown look different on two sites?

They run different processors. A line using a GFM or Pandoc extension renders on a tool that supports it but not on a plain CommonMark one.

Footnotes aren't in core CommonMark; they come from MultiMarkdown and Pandoc, and GitHub supports them too. They're a flavor feature, so check support.

Where to go next: now turn your Markdown into a real site. Continue to Publishing with MkDocs, Hugo and Jekyll to convert .md files into HTML pages.

Practice quiz

• Browse all free courses
• Cheat sheets & quizzes
• Coding dictionary