GitHub Flavored Markdown: Everything You Need to Know

GitHub Flavored Markdown (GFM) is a superset of CommonMark — the standardized markdown spec. GitHub added extensions for features developers use every day: tables, task lists, syntax highlighting, autolinks, and more.

Standard vs. GFM-Only

Task Lists

markdown
- [x] Set up CI/CD pipeline
- [x] Write unit tests
- [ ] Update documentation
- [ ] Deploy to staging

Checkboxes are clickable in GitHub issues and pull requests.

Nested:

markdown
- [ ] Release v2.0
  - [x] Feature A
  - [ ] Migration guide

Syntax Highlighting

markdown
```typescript
async function getUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}

Common language identifiers: `bash`, `javascript`/`js`, `typescript`/`ts`, `python`/`py`, `go`, `rust`, `json`, `yaml`, `sql`, `diff`

**Diff highlighting:**
```diff
- const url = 'http://api.example.com';
+ const url = process.env.API_URL;

Strikethrough

markdown
~~This approach is deprecated.~~ Use the new API instead.

GitHub Auto-links

GitHub auto-links these references:

• URLs: https://example.com → clickable link
• Issues: #123 → links to issue 123
• PRs: #456 → links to PR 456
• Commit SHAs: a5c3785 → links to commit
• Mentions: @username → links to profile
• Cross-repo: user/repo#123 → cross-repo issue

Emoji Shortcodes

markdown
:rocket: :tada: :white_check_mark: :warning: :bulb: :fire:

Renders as: 🚀 🎉 ✅ ⚠️ 💡 🔥

Use sparingly in professional docs.

Footnotes

markdown
Here is a statement that needs a citation.[^1]

[^1]: Smith, J. (2024). *Source Title*. Publisher.

GitHub Alerts (2023+)

markdown
> [!NOTE]
> Useful information users should know, even when skimming.

> [!WARNING]
> Critical content demanding immediate attention due to potential risks.

> [!IMPORTANT]
> Critical information necessary for users to succeed.

These render with colored icons on GitHub only.

Collapsed Sections

markdown
<details>
<summary>Click to expand</summary>

Hidden content here. Markdown works inside.

</details>

GFM Compatibility

Works on: GitHub, GitLab (mostly), VS Code preview, MarkGenie

May not work on: older CMS systems, plain CommonMark parsers

Test your GFM markdown live in MarkGenie before pasting into your README.