CommonMark vs GFM: Which Markdown Standard Should You Use? (2026)
CommonMark and GitHub Flavored Markdown explained — syntax differences, portability matrix, platform support tables, and a decision framework for READMEs, docs, chat, and AI pipelines.
Markdown is not one language — it is a family of dialects. Two names dominate technical writing in 2026: CommonMark, the formal specification, and GitHub Flavored Markdown (GFM), the superset every README and issue tracker assumes you know.
Paste the same file into Slack, Reddit, and your static site generator and you will get three different renderings. That is not a bug in your editor — it is the cost of Markdown's popularity without a single enforced standard.
This guide explains what each standard includes, where they diverge, which platforms support which extensions, and how to choose the right subset for your audience.
The short answer
| If you are writing for… | Use |
|---|---|
| Maximum portability (email, legacy tools) | CommonMark only |
| GitHub, GitLab, docs sites, npm | GFM |
| Slack messages | mrkdwn (not GFM — see Slack guide) |
| Reddit posts | Reddit-flavored (GFM + spoilers — see Reddit guide) |
| Obsidian vault | GFM + wikilinks |
| AI output pipelines | GFM, then validate before render |
When in doubt for developer content: write GFM, avoid platform-specific syntax, preview in your target renderer.
History: from Markdown to two standards
John Gruber published Markdown in 2004 as a readable-to-write, readable-as-plain-text format. He deliberately left edge cases ambiguous — which led to incompatible implementations across PHP Markdown, Pandoc, Reddit, and early GitHub.
CommonMark (2014, John MacFarlane et al.) published a formal spec with 600+ conformance tests. If a parser passes CommonMark tests, *emphasis* and list nesting behave predictably.
GFM (GitHub, evolving spec at github.github.com/gfm) adds practical extensions on top of CommonMark:
- Tables
- Task lists (
- [ ]) - Strikethrough (
~~text~~) - Autolinks (
https://example.com) - Fenced code blocks with language tags (now in CommonMark 0.30+)
- Footnotes (
[^1]) - Alerts (
> [!NOTE]) - Mermaid diagrams (fenced
mermaidblocks, GitHub-native)
GFM is what your README.md renders as on GitHub. It is the de facto standard for open source even though it is not identical to CommonMark.
Side-by-side: core syntax
These constructs work the same in CommonMark and GFM:
# Heading 1
## Heading 2
**bold** and *italic*
- Bulleted list
1. Numbered list
> Blockquote
`inline code`
[Link text](https://example.com)

Fenced code blocks
CommonMark 0.30+ and GFM both support:
```typescript
const x: number = 1;
```
The language-typescript class on the <code> element enables syntax highlighting. See the code blocks guide.
What GFM adds beyond CommonMark
| Extension | GFM syntax | CommonMark |
|---|---|---|
| Tables | | col | pipes | ❌ |
| Task lists | - [ ] / - [x] | ❌ |
| Strikethrough | ~~text~~ | ❌ |
| Autolinks | bare https://… | partial |
| Footnotes | [^1] + [^1]: | ❌ |
| Alerts | > [!WARNING] | ❌ |
| Mermaid | ```mermaid | ❌ |
| Disallowed HTML filter | strips dangerous tags | renderer-dependent |
GFM tables
| Feature | CommonMark | GFM |
| ------- | :--------: | :-: |
| Tables | ❌ | ✅ |
Build tables visually in the table generator. Misaligned pipes break rendering — run the GFM checklist before commit.
GFM task lists
- [x] Ship v2.0 API
- [ ] npm SDK
- [ ] GitHub Action
Task lists are clickable on GitHub issues and PRs. They do not work in Slack, Discord, or email.
GFM footnotes
GitHub added footnotes in 2021.[^gfm]
[^gfm]: See the GFM spec section on footnotes.
Deep dive: Markdown footnotes guide.
GFM alerts
> [!NOTE]
> GFM alerts render as colored callout blocks on GitHub.
> [!WARNING]
> Breaking change in the next major version.
Obsidian uses a related callout syntax (> [!note]) — see Obsidian guide.
Platform support matrix (2026)
| Platform | Base | Tables | Tasks | Footnotes | Mermaid | Spoilers |
|---|---|---|---|---|---|---|
| GitHub | GFM | ✅ | ✅ | ✅ | ✅ | ❌ |
| GitLab (GLFM) | GFM+ | ✅ | ✅ | ✅ | ✅ | ❌ |
| VS Code preview | GFM | ✅ | ✅ | ⚠️ | ext. | ❌ |
| Stack Overflow | CommonMark | ❌ | ❌ | ❌ | ❌ | block |
| Reddit (snoomark) | GFM-ish | ✅ | ❌ | ❌ | ❌ | >!!< |
| Discord | subset | ❌ | ❌ | ❌ | ❌ | || |
| Slack (mrkdwn) | custom | ❌ | ❌ | ❌ | ❌ | ❌ |
| Notion | partial | ⚠️ | ✅ | ❌ | ❌ | ❌ |
| Obsidian | GFM+ | ✅ | ✅ | ✅ | ✅ | ❌ |
| Hugo (Goldmark) | GFM | ✅ | ✅ | ✅ | plugin | ❌ |
| Docusaurus | MDX+GFM | ✅ | ✅ | ✅ | ✅ | ❌ |
⚠️ = needs extension or paste behavior varies.
Portable intersection: CommonMark + tables + fenced code. That covers ~80% of readers without platform lock-in.
CommonMark-only: when to restrict yourself
Choose strict CommonMark when:
- Email newsletters — many clients strip tables and task lists.
- Comments on older forums — pre-GFM parsers.
- Maximum future-proofing — content may render in unknown tools.
- Lint enforcement — some corporate style guides mandate CommonMark subset.
Test with the syntax tutor and validate API.
GFM: when to use the full extension set
Choose GFM when:
- GitHub READMEs and issues — default renderer.
- Documentation sites (Hugo, MkDocs, Docusaurus) — GFM expected.
- Technical specs with comparison tables and checklists.
- API documentation with code samples and admonitions.
Validate structure with audit GFM in CI.
MDX: the third option
MDX embeds JSX components inside Markdown:
import { Callout } from "@/components/callout";
# Installation
<Callout type="warning">Requires Node 18+</Callout>
MDX is not CommonMark or GFM — it is a programming environment. Use MDX when you need interactive widgets in docs; keep prose-heavy content in plain .md for portability.
Cross-platform authoring strategy
Professional teams writing for multiple destinations use a lowest common denominator draft:
1. Write GFM body (tables, tasks, code fences)
2. Strip platform-specific syntax for Slack/Discord copies
3. Preview in target renderer before publish
4. Store canonical copy in Git as .md
| Destination | Transform |
|---|---|
| GitHub → Slack | **bold** → *bold*; fix links to <url|label> |
| GitHub → Reddit | Usually works; verify spoilers separately |
| Notion → GitHub | Paste via HTML to Markdown |
| AI → GitHub | Clean ChatGPT output |
Parsing and rendering in your app
If you build software that renders user Markdown:
| Approach | Pros | Cons |
|---|---|---|
| CommonMark parser only | Predictable spec | No tables without extension |
| remark + remark-gfm | Full GFM in JS | You own sanitization |
| Markdown Viewer API | Matches browser tools, sanitized | Network dependency |
curl -X POST https://trymarkdownviewer.com/api/v1/render \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"markdown": "# Hello\n\n| a | b |\n|---|---|\n| 1 | 2 |"}'
Same GFM the editor preview uses. Docs: api-render.
Common mistakes
1. Assuming all Markdown is GFM. Stack Overflow and email are not.
2. Using Slack syntax on GitHub. *bold* in Slack ≠ **bold** on GitHub.
3. Tables without separator row. Header must be followed by |---|---|.
4. Task lists in code blocks. Checkbox syntax inside fences renders literally.
5. Footnotes in CommonMark-only tools. They appear as raw [^1] text.
6. Not previewing. One pipe character breaks a table — always preview.
Decision flowchart
Who reads this?
├─ GitHub / GitLab / docs site → GFM (full)
├─ Slack only → mrkdwn rules
├─ Reddit only → GFM + Reddit extensions
├─ Unknown / email → CommonMark core only
└─ User-generated in your app → GFM + sanitize + API validate
Related articles
- Markdown syntax guide — CommonMark walkthrough
- Markdown cheat sheet — quick reference
- Markdown vs HTML — format tradeoffs
- GitHub README guide — GFM in practice
- Reddit Markdown guide — snoomark quirks
- Slack Markdown guide — mrkdwn rules
Quick reference
| Standard | Includes |
|---|---|
| CommonMark | Headings, emphasis, lists, quotes, links, images, fenced code |
| GFM adds | Tables, tasks, ~~strike~~, autolinks, footnotes, alerts, Mermaid |
| GitLab adds | GLFM cross-refs (#123, @user), math, diagrams |
| Not portable | Slack mrkdwn, Reddit spoilers, Obsidian wikilinks, MDX components |
Pick the standard your reader's renderer expects, not the standard that is easiest to write. For most developer content in 2026, that means GFM — with your eyes open about what will break when the same text leaves GitHub.
Written by Markdown Viewer Team. Found this useful? Try the editor →
Keep reading
Hand-picked articles related to this one.
How to write Markdown footnotes on GitHub, GitLab, and Obsidian — reference syntax, multi-paragraph notes, citations, export quirks, and tools to validate footnote pairs.
The in-depth GitHub README playbook — star-winning structure, GFM tables and alerts, Mermaid diagrams, profile READMEs, badges, CI snippets, anti-patterns, and a copy-paste template.
A power-user tutorial for advanced Markdown tasks — diffing revisions, validating Mermaid, redacting secrets, normalizing structure, merging and splitting docs, and managing footnotes.