Skip to content
All posts
7 min read
markdown
commonmark
gfm
standards
guide

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, npmGFM
Slack messagesmrkdwn (not GFM — see Slack guide)
Reddit postsReddit-flavored (GFM + spoilers — see Reddit guide)
Obsidian vaultGFM + wikilinks
AI output pipelinesGFM, 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 mermaid blocks, 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)

![Alt text](image.png)

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

ExtensionGFM syntaxCommonMark
Tables| col | pipes❌
Task lists- [ ] / - [x]❌
Strikethrough~~text~~❌
Autolinksbare https://…partial
Footnotes[^1] + [^1]:❌
Alerts> [!WARNING]❌
Mermaid```mermaid❌
Disallowed HTML filterstrips dangerous tagsrenderer-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)

PlatformBaseTablesTasksFootnotesMermaidSpoilers
GitHubGFM✅✅✅✅❌
GitLab (GLFM)GFM+✅✅✅✅❌
VS Code previewGFM✅✅⚠️ext.❌
Stack OverflowCommonMark❌❌❌❌block
Reddit (snoomark)GFM-ish✅❌❌❌>!!<
Discordsubset❌❌❌❌||
Slack (mrkdwn)custom❌❌❌❌❌
Notionpartial⚠️✅❌❌❌
ObsidianGFM+✅✅✅✅❌
Hugo (Goldmark)GFM✅✅✅plugin❌
DocusaurusMDX+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:

  1. Email newsletters — many clients strip tables and task lists.
  2. Comments on older forums — pre-GFM parsers.
  3. Maximum future-proofing — content may render in unknown tools.
  4. 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:

  1. GitHub READMEs and issues — default renderer.
  2. Documentation sites (Hugo, MkDocs, Docusaurus) — GFM expected.
  3. Technical specs with comparison tables and checklists.
  4. 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
DestinationTransform
GitHub → Slack**bold** → *bold*; fix links to <url|label>
GitHub → RedditUsually works; verify spoilers separately
Notion → GitHubPaste via HTML to Markdown
AI → GitHubClean ChatGPT output

Parsing and rendering in your app

If you build software that renders user Markdown:

ApproachProsCons
CommonMark parser onlyPredictable specNo tables without extension
remark + remark-gfmFull GFM in JSYou own sanitization
Markdown Viewer APIMatches browser tools, sanitizedNetwork 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

Quick reference

StandardIncludes
CommonMarkHeadings, emphasis, lists, quotes, links, images, fenced code
GFM addsTables, tasks, ~~strike~~, autolinks, footnotes, alerts, Mermaid
GitLab addsGLFM cross-refs (#123, @user), math, diagrams
Not portableSlack 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.