What GFM adds on top of CommonMark
GitHub Flavored Markdown (GFM) is a formally specified superset of CommonMark — everything CommonMark supports, plus several extensions GitHub added for practical use in READMEs, issues, and pull requests:
Task lists
- [x] Completed item
- [ ] Pending item
Renders as interactive (on GitHub) or static checkboxes — genuinely useful for tracking checklist-style content directly in a README or issue description, without needing a separate task-tracking tool for something simple.
Tables
Covered in depth in Markdown Tables — pipe-delimited rows with a required dashed separator row, another GFM addition not present in bare CommonMark.
Strikethrough
~~this text is struck through~~
A straightforward extension for marking text as removed or outdated without deleting it outright.
Alerts (a newer, GitHub-specific addition)
> [!NOTE]
> Useful information that users should know.
> [!WARNING]
> Critical content demanding immediate attention.
Alerts are a relatively recent GitHub-specific extension, styling specially-marked blockquotes as colored callout boxes (Note, Tip, Important, Warning, Caution). This is a more GitHub-specific feature than the older, more widely-adopted extensions — support elsewhere is inconsistent, and it's worth checking whether your target renderer supports it before relying on the exact syntax.
Autolinking bare URLs
GFM automatically turns a bare URL or recognized reference (like #123 for an issue number, within GitHub itself) into a clickable link without needing explicit [text](url) syntax — a convenience most plain CommonMark renderers don't replicate automatically.
Why this matters for portability
Every extension covered here works reliably on GitHub itself, but portability varies once content moves elsewhere — a README with task lists and tables generally renders fine on most platforms that adopted the popular GFM extensions, but alerts and GitHub-specific autolinking (like #123 issue references) are far less consistently supported outside GitHub's own rendering. Content meant to display correctly in multiple places should be tested against each target renderer rather than assumed to work identically everywhere.
Common mistakes
- Assuming GFM alerts render the same way on every platform. They're a newer, more GitHub-specific feature — many other Markdown renderers (including some static site generators) don't support the exact
[!NOTE]syntax without additional configuration or a plugin. - Relying on GitHub-specific autolinking (like
#123) in content meant for other platforms. This shorthand is tied to GitHub's own issue/PR referencing system, not general Markdown. - Forgetting task list checkboxes are just styled Markdown, not a real database. They track state visually within the rendered document, not as an actual persistent task-management system elsewhere.
FAQ
Are GitHub Flavored Markdown extensions part of the official CommonMark spec?
No — GFM is a separately specified superset that CommonMark's core spec doesn't include; support for GFM-specific features varies across other tools and renderers.
Do GFM alerts ([!NOTE], [!WARNING]) work everywhere?
Not reliably — this is a newer, more GitHub-specific extension; check your target platform's documentation before depending on this exact syntax rendering as intended.
Will a task list checkbox stay checked if I move the Markdown file to another platform?
The checkbox state is just part of the Markdown text itself ([x] vs [ ]) — it persists as plain text regardless of platform, though whether it renders as an interactive or static checkbox depends on that platform's renderer.
Learn the broader Markdown syntax landscape in the Complete Guide to Markdown.