GitHub Flavored Markdown

GitHub Flavored Markdown is a formal specification, published by GitHub, defined as CommonMark plus five extensions: tables, task list items, strikethrough, autolinks, and a rule that disallows certain raw HTML tags. That is the whole of the spec. Any parser advertising GFM support means those five.

Everything else people associate with GitHub — footnotes, alert callouts, emoji shortcodes, @ mentions, issue references, Mermaid diagrams — is a GitHub platform feature applied on top when rendering on the site. The distinction matters: the five spec extensions work in dozens of parsers, this one included. The platform features generally do not work anywhere but GitHub.

Underneath all of it is CommonMark, which fixed the ambiguities in the original 2004 Markdown. If you want the base layer, that is the Markdown guide.

The single most-used extension. A header row, a divider row of dashes, then body rows, with pipes between cells and colons in the divider setting the alignment. Cells take inline formatting but not block-level syntax, so no lists or headings inside a cell.

Tables are so widely implemented that many people assume they are core Markdown. They are not: a strict CommonMark parser, Slack and Discord all show them as raw pipes. The tables guide covers alignment, escaped pipes and the merged-cell question in full.

| Package | Version | Licence |
| :-- | --: | :-: |
| core | 3.1.0 | MIT |
| cli | 1.9.4 | MIT |

A bracketed space or x immediately after a list marker becomes a checkbox. The spacing is exact and unforgiving: marker, space, open bracket, space or x, close bracket, space, text.

On GitHub these are interactive. Ticking a box in an issue or pull request body rewrites the underlying Markdown and updates a progress counter in the issue list — which is why task lists have become the default way teams track sub-work without a separate tool. Outside GitHub they render as read-only checkboxes, including here. Nesting works, and the sub-items count toward the parent's progress on GitHub.

- [x] Write the migration
- [x] Review
- [ ] Run against staging
- [ ] Ship

Two tildes either side strike text through. GitHub also accepts a single tilde; the GFM spec requires two, so write two if the document travels.

The autolink extension turns a bare URL into a link without any markup — and, unlike the CommonMark autolink, it does not need a scheme, so a bare www.example.com links too. This viewer does the same. It is convenient and occasionally annoying: a trailing full stop is usually excluded correctly, but a URL inside parentheses can pick up the closing bracket. If a bare URL links wrongly, write it as a proper inline link instead, as described in the links guide.

~~Deprecated in 3.0~~ — removed in 4.0.

Docs at www.example.com and https://example.com/api.

GitHub renders footnotes: a marker in the text, and a definition elsewhere in the file. GitHub collects the definitions at the bottom of the rendered document, numbers them in order of appearance and adds a return arrow, regardless of the labels you used or where you put the definitions.

This is a GitHub platform feature, not part of the GFM spec. Some other parsers support the same syntax through a plugin; many do not. This viewer does not support footnotes — the markers and the definitions both appear as literal text, exactly as shown below. If a document needs to read correctly here or in an export, use a parenthetical or a linked reference instead.

Revenue rose 12%[^rev] year on year.

[^rev]: Measured on constant currency.

GitHub renders five kinds of alert: a block quote whose first line is [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION], followed by the content on the lines below. Each gets a coloured border and an icon. The keyword is case-sensitive and must be on its own line.

This is the newest of the GitHub-only features and is spreading — Azure DevOps and some documentation tools support a similar syntax, and Obsidian has its own callouts using a slightly different marker. This viewer does not support alerts. An alert here renders as an ordinary block quote with the bracketed keyword visible on the first line, which is at least readable, but it is not the effect you wrote.

> [!WARNING]
> Running this against production deletes unversioned rows.

Three shorthands that only mean anything on github.com. :tada: and the rest of the emoji shortcodes expand to the emoji character. An @ followed by a username links to that person's profile and notifies them. A # followed by a number links to that issue or pull request in the same repository, and a full owner/repo#123 links across repositories. A bare 40-character commit SHA becomes a link to that commit.

Elsewhere all four are literal text — which is a real hazard in a README, since #123 looks like nothing and @name can trigger a notification somewhere you did not intend. Type the actual emoji character rather than a shortcode if you want it to survive; it is plain Unicode and works everywhere, including in exports.

GitHub renders README.md at the root of a repository, and also inside any folder you browse to, which makes per-directory READMEs a cheap way to document a codebase. A few conventions are worth knowing.

Headings get generated anchor ids, so you can link between sections and GitHub's own table-of-contents button uses them. Relative links to other files in the repo are resolved for you, and are the form that survives forks. Images should be relative paths to committed files, not blob URLs. A CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md or issue template in .github/ is picked up automatically. And a fenced block tagged mermaid is rendered as a diagram rather than as code — see the Mermaid guide.

Supported: everything in CommonMark, plus tables, task lists, strikethrough and automatic linking of bare URLs. In practice that covers the overwhelming majority of real documents, and it is what the cheat sheet documents.

Not supported, deliberately and explicitly:

• Footnotes. Markers and definitions render as text.
• Alerts such as > [!NOTE]. They render as ordinary block quotes.
• Emoji shortcodes, mentions and issue references. All literal text.
• Raw HTML. Disabled entirely rather than filtered, so a pasted document can never inject markup or script into this page. GFM's rule only disallows a handful of tags; we allow none.

Mermaid fences are the one addition in the other direction: they draw as diagrams here, as they do on GitHub.