GitHub Flavored Markdown (GFM): Syntax & Examples

GitHub Flavored Markdown (GFM) is CommonMark plus five formal extensions: tables, task list items, strikethrough, extended autolinks, and tag filtering. GitHub.com also renders alerts, mentions, emoji, math, and Mermaid, but those platform features are not part of the GFM specification.

Use this distinction when choosing portable syntax. For a compact core reference, keep the Markdown cheat sheet nearby.

What GFM adds on top of CommonMark

The formal GFM specification is based on CommonMark and adds:

1. Tables
2. Task lists
3. Strikethrough
4. Autolinks
5. Tag filtering

Plus GitHub.com adds some platform-specific rendering (emoji shortcodes, @mentions, issue linking, Mermaid diagrams) that isn't strictly in the GFM spec but travels with it.

Let's go through each.

1. Tables

Pipe-separated tables with an alignment row:

| Name    | Role    | Score |
| :------ | :-----: | ----: |
| Alice   | Admin   |   100 |
| Bob     | Editor  |    85 |
| Charlie | Viewer  |    42 |

Renders as:

Alignment is set by the colons in the second row:

• :--- → left
• :---: → center
• ---: → right
• --- → default (usually left)

Tips:

• You don't need to align the pipes visually — most editors do it for you.
• Don't try to nest tables. Markdown doesn't support it. Use HTML if you absolutely must.
• Tables can contain inline Markdown: links, bold, code, images.
• Tables cannot contain: block-level elements (paragraphs, lists, code blocks). Keep it simple.

If manually typing tables is painful, use our Markdown Table Generator.

2. Task lists

Unordered list items with a checkbox:

- [x] Write the README
- [ ] Add CI pipeline
- [ ] Publish to npm

Renders with interactive-looking checkboxes. On GitHub.com issue comments, they become actually interactive — you can click to toggle.

Notes:

• A lowercase x between brackets means checked. [X] (uppercase) also works on GitHub but isn't spec.
• You can't have an unchecked state with anything other than a space between the brackets: [ ].
• Task lists can be nested.
• Great for README roadmaps, PR descriptions ("Acceptance criteria"), and issue templates.

3. Strikethrough

~~This text is struck through.~~

Renders as: This text is struck through.

One tilde (~text~) does not work in GFM — you need two. This distinguishes GFM from some other Markdown dialects where single-tilde is valid.

4. Autolinks

Naked URLs become clickable links:

Visit https://mdkit.io for free tools.
Contact us at [email protected].

CommonMark requires you to wrap URLs in angle brackets: <https://example.com>. GFM auto-detects bare URLs and email addresses.

This is extremely convenient in issue comments and quick notes.

5. Tag filtering

GFM's tag-filter extension escapes the opening < of selected raw HTML tags, including script, style, iframe, title, and textarea. It is a parsing rule, not a complete HTML sanitizer. Applications that render untrusted Markdown still need an appropriate sanitization policy.

List continuation and indentation come from CommonMark; GFM does not define a separate multiline-list extension.

GitHub.com-specific extras

These aren't strictly GFM, but they work when your Markdown is rendered on GitHub.

Emoji shortcodes

:rocket: :heart: :sparkles: :+1:

Renders as: 🚀 ❤️ ✨ 👍

Full list: github.com/ikatyang/emoji-cheat-sheet.

Works on: GitHub.com, GitLab, Mattermost, some chat apps.
Does not work on: raw CommonMark renderers (unless you add an emoji plugin like remark-emoji).

@mentions

@octocat please review this PR.

Links to user profiles on GitHub. Behavior varies elsewhere.

Issue and PR references

Fixes #42.
See also user/repo#101.

Auto-linked to the issue or PR on GitHub.

Commit SHAs

See a5c3785 for the fix.

GitHub auto-links 7–40 character hex strings to commits.

Mermaid diagrams

```mermaid
graph LR
  A[Idea] --> B[PRD]
  B --> C[Design]
  C --> D[Ship]
```

GitHub renders Mermaid blocks as actual diagrams. So do GitLab, Obsidian, and Notion. Plain CommonMark shows them as code blocks.

Math

Inline math: $E = mc^2$

Block math:

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

GitHub renders mathematical expressions with MathJax. Other tools may use MathJax, KaTeX, or no math extension, so test the target renderer.

GitHub-specific alerts

GitHub alerts use blockquote-like syntax on GitHub.com, but they are not part of the formal GFM specification:

> [!NOTE]
> Highlights information users should know.

> [!TIP]
> Optional, but helpful advice.

> [!IMPORTANT]
> Crucial information.

> [!WARNING]
> Urgent; needs attention.

> [!CAUTION]
> Negative consequences of an action.

Use alerts only where the target renderer documents support.

Check compatibility by feature

Do not rely on a platform-wide "supports GFM" label. Preview a representative document containing a table, task list, strikethrough, a bare URL, and any raw HTML you need. GitHub-only features such as alerts, mentions, issue references, math, Mermaid, and emoji require separate checks.

How to enable GFM in your toolchain

Marked (JavaScript)

import { marked } from "marked";
marked.use({ gfm: true, breaks: false });
const html = marked.parse(markdownText);

remark / rehype (unified ecosystem)

npm install remark remark-gfm remark-rehype rehype-stringify

import { unified } from "unified";
import remarkParse from "remark-parse";
import remarkGfm from "remark-gfm";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";

const html = await unified()
  .use(remarkParse)
  .use(remarkGfm)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process(markdownText);

Markdown-it (JavaScript)

import MarkdownIt from "markdown-it";
const md = new MarkdownIt({ html: true, linkify: true });
// Tables, autolinks, etc. are on by default.
// Task lists need markdown-it-task-lists plugin.

Pandoc

pandoc input.md -o output.html --from=gfm

Python (mistune, markdown-it-py)

from markdown_it import MarkdownIt
md = MarkdownIt("gfm-like").enable("table").enable("strikethrough")
html = md.render(markdown_text)

Practical gotchas

Autolinks in code

Check the URL: `https://example.com`

Inside backticks, autolinking is disabled (as it should be). Don't try to put links inside code spans.

Tables and line wrapping

Long table cells force wide horizontal scrolling on mobile. Consider splitting into multiple tables or using a definition list (HTML) for complex data.

Task list persistence

GitHub persists task list state when you edit the Markdown — but only in issues, PRs, and comments. In README files, toggling a checkbox doesn't save automatically (it opens the editor).

Nested lists in tables

| Feature | Notes           |
| :------ | :-------------- |
| Auth    | - OAuth<br>- JWT |

Lists inside table cells don't work in GFM. The workaround is <br> tags for line breaks, or structuring your content differently (use an H3 plus a list under the table).

Blockquote + list interaction

> Here's a quote:
> - item one
> - item two

Works. But forget the leading > on a continuation line and the rendering falls apart. Be consistent.

Summary

• Formal GFM adds tables, task list items, strikethrough, extended autolinks, and tag filtering to CommonMark.
• GitHub.com features such as alerts, mentions, emoji, math, and Mermaid are separate.
• Add remark-gfm (or equivalent) when your toolchain does not already enable the extensions.
• Stick to GFM core for maximum portability; reserve GitHub-specific features (emoji, @mentions, alerts) for content that will only be rendered on GitHub.

You now know exactly what GFM adds and where it works. For a full syntax refresher, see our Markdown Cheat Sheet. For tables specifically, read Markdown Tables: syntax, alignment, and generators.