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.

What You'll Learn

💡 Real-World Analogy

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.

• a bullet list
• another item

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.

• a pending task

Col A

Col B

1

2

🎯 Your Turn #1: portable core only

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).

• Gruber Markdown (2004) — the original, loosely specified
• CommonMark — a strict, testable standard for the core
• GFM — CommonMark + tables, task lists, strikethrough, autolinks
• MultiMarkdown — adds footnotes, tables, metadata, citations
• Pandoc Markdown — highly extensible, built for converting between formats

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.

🎯 Your Turn #2: a GFM-only feature

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.

Common Errors (and the fix)

• My table is plain text elsewhere. Tables are a GFM extension, not core CommonMark. On non-GFM viewers, use a code block or a simple list instead.
• Tildes show literally. Strikethrough ~~...~~ is GFM-only. Drop it for core-only audiences, or move the doc to GitHub.
• Checkboxes render as [ ] text. Task lists are GFM. Plain bullets are the portable fallback.
• Bare URL isn't clickable. Autolinking bare URLs is a GFM behaviour; in core, wrap the URL: <https://example.com> or use [text](url) .
• Same file, different output. You're relying on a flavor the second tool doesn't share. Identify which feature is flavor-specific and replace it with core syntax.

📋 Quick Reference — Flavors

Feature

Flavor

Headings, emphasis, lists, links

Core (CommonMark)

Fenced code blocks

Tables

GFM extension

Task lists - [ ]

Strikethrough ~~ ~~

Footnotes, citations

MultiMarkdown / Pandoc

Many output formats

Pandoc

Mini-Challenge: A Portability Report

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.

Pro Tips

• 💡 Know your target. Writing for GitHub? GFM is fine. Writing for an unknown viewer? Stay in the core.
• 💡 Prefer reference links and core lists. They render identically across flavors, unlike tables and task lists.
• 💡 Test in two tools. Render the same file in CommonMark and in GitHub to spot flavor-specific lines.
• 💡 Reach for Pandoc to convert. When you must move Markdown to DOCX, PDF, or LaTeX, Pandoc handles the most formats.

Frequently Asked Questions

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.

Lesson Complete! 🎉

• ✅ CommonMark is the strict, standardised spec for core Markdown
• ✅ GFM is a superset adding tables, task lists, strikethrough, and autolinks
• ✅ The original Gruber Markdown was loosely defined, so flavors diverged
• ✅ MultiMarkdown and Pandoc add footnotes, citations, and broad conversion
• ✅ Portable Markdown sticks to the shared core that renders everywhere

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

Continue this course

• Previous: Math with LaTeX
• Next: Publishing with MkDocs, Hugo and Jekyll