• Use GFM when your content lives on GitHub, GitLab, or another platform that renders it natively — its extensions are well supported and the output is predictable.
• Prefer [x] (lowercase) in task lists — some renderers do not recognise [X].
• Be aware that GFM tables require a header row; you cannot create a table without one.
• Do not rely on GFM extensions (tables, task lists, strikethrough) if you need the file to display correctly on platforms that only support plain CommonMark.

Origin

GitHub developed its own Markdown extensions long before they were formally specified. Tables appeared on GitHub as early as 2009; task lists and strikethrough followed over the next few years. For years, the behaviour was documented only informally in GitHub's help pages.

In August 2017, GitHub published the GitHub Flavoured Markdown Specification, a precise document modelled on the CommonMark spec. GFM is officially a strict superset of CommonMark — anything valid in CommonMark is valid in GFM.

What GFM Adds to CommonMark

Tables

GFM defines a pipe-separated table syntax with a mandatory header row and a separator row of hyphens. Column alignment is controlled by colons in the separator row.

| Destination | Best season | Journey time |
| --- | --- | --- |
| Lisbon | Spring or autumn | 2.5 hours by air |
| Edinburgh | Summer | 1.5 hours by air |
| Bruges | Year-round | 2 hours by Eurostar |

Task lists

Task list items use [ ] for an open checkbox and [x] for a ticked one. On GitHub, ticking a checkbox edits the underlying Markdown source directly.

- [x] Pack walking boots
- [x] Book the ferry
- [ ] Arrange cat sitting
- [ ] Print boarding passes

Strikethrough

Text wrapped in double tildes is rendered with a line through it.

~~First draft title~~ A Better Title

Extended autolinks

GFM automatically converts bare URLs such as https://example.com into clickable links, without needing angle brackets or inline link syntax.

Disallowed raw HTML

GFM strips certain HTML elements for security reasons, including <script>, <style>, <iframe>, and a small number of others. These are filtered out and rendered as plain text rather than executed.

The Spec vs. GitHub's Live Rendering

The GFM specification defines exactly the extensions listed above. In practice, GitHub's rendering engine goes further with features that are part of the product but not the spec:

• Syntax highlighting — fenced code blocks with a language tag are syntax-coloured
• Mermaid diagrams — fenced blocks tagged mermaid are rendered as diagrams
• Blockquote alerts — > [!NOTE], > [!TIP], > [!WARNING], > [!CAUTION], and > [!IMPORTANT] produce styled callout boxes
• Emoji shortcodes — :tada: is rendered as 🎉

These extras are part of GitHub's platform, not the GFM spec. Other GFM-compatible renderers may not support them.

Compatibility

Tools that use GFM or a closely compatible dialect:

• GitHub — the reference implementation
• GitLab — GFM-compatible with some additions
• VS Code — the built-in Markdown preview renders GFM
• Discord — a GFM subset
• Obsidian — GFM-compatible core with its own extensions on top