GitHub Flavored Markdown: Complete Guide & Cheat Sheet

What is GitHub Flavored Markdown (GFM)?

GitHub Flavored Markdown (GFM) is GitHub's extension of standard markdown. It adds powerful features like task lists, tables, @mentions, automatic URL linking, strikethrough, and syntax highlighting. GFM is used everywhere on GitHub: READMEs, issues, pull requests, comments, discussions, and wikis.

This guide covers everything unique to GFM that standard markdown doesn't have. For basic markdown syntax, see our Technical Documentation Guide.

1. Task Lists (Checkboxes)

One of GFM's most popular features. Perfect for TODO lists, feature checklists, and tracking progress.

- [ ] Unchecked task
- [x] Completed task
- [ ] Another pending task
  - [ ] Nested subtask
  - [x] Completed subtask

Renders as:

• ☐ Unchecked task
• ☑ Completed task
• ☐ Another pending task
  • ☐ Nested subtask
  • ☑ Completed subtask

2. Tables

GFM tables support alignment and full markdown formatting inside cells. Learn more in our dedicated Markdown Table Generator Guide.

| Feature | Status | Notes |
|---------|:------:|-------|
| Tables | ✅ | Fully supported |
| Task lists | ✅ | Interactive on GitHub |
| Emoji | ✅ | :rocket: :fire: |
| Mentions | ✅ | @username support |

3. Strikethrough Text

Use double tildes to strike through text:

~~This text is crossed out~~
This is ~~partially~~ struck through

Renders as: This text is crossed out

4. Automatic URL Linking

GFM automatically converts URLs to clickable links. Standard markdown requires explicit link syntax.

https://github.com  ← Automatically becomes a link
www.example.com     ← Also auto-linked

5. Mentions and References

GitHub's most social feature. Mention users, teams, and reference issues/PRs.

@username           ← Mention a user
@org/team-name      ← Mention a team
#123                ← Reference issue/PR #123
user/repo#456       ← Cross-repo reference
GH-789              ← Alternative reference syntax

6. Emoji Support

GitHub supports hundreds of emoji via shortcodes. Add personality and visual cues to your markdown.

:rocket: :fire: :tada: :thumbsup: :heart:
:warning: :bug: :sparkles: :zap: :art:

Renders as: 🚀 🔥 🎉 👍 ❤️ ⚠️ 🐛 ✨ ⚡ 🎨

7. Syntax Highlighting in Code Blocks

GFM supports syntax highlighting for 100+ languages. Specify the language after the opening backticks.

```javascript
function hello(name) {
  console.log(`Hello, ${name}!`);
}
```

```python
def hello(name):
    print(f"Hello, {name}!")
```

```bash
npm install
npm run build
```

Supported languages include: javascript, typescript, python, java, go, rust, php, ruby, swift, kotlin, c, cpp, csharp, html, css, scss, json, yaml, sql, bash, shell, dockerfile, and many more.

8. Diff Syntax in Code Blocks

Show code changes with diff highlighting:

```diff
- const oldValue = 10;
+ const newValue = 20;
  
  function calculate() {
-   return oldValue * 2;
+   return newValue * 2;
  }
```

9. Footnotes

Add footnotes for citations and additional information:

Here's a statement with a footnote[^1].

Another statement with a footnote[^2].

[^1]: This is the first footnote.
[^2]: This is the second footnote with more detail.

10. Alerts and Callouts (New in 2023)

GitHub recently added special blockquote syntax for alerts:

> [!NOTE]
> Useful information that users should know

> [!TIP]
> Helpful advice for doing things better

> [!IMPORTANT]
> Key information users need to know

> [!WARNING]
> Urgent info that needs immediate attention

> [!CAUTION]
> Advises about risks or negative outcomes

11. Collapsed Sections (Details/Summary)

Use HTML details/summary tags for collapsible content:

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

Hidden content here. You can use:
- Markdown lists
- **Bold text**
- Code blocks
- Whatever you need!

</details>

12. Escaping Special Characters

Use backslash to escape markdown syntax:

\* Not a bullet point
\# Not a header
\[Not a link\](url)
\` Not code \`

GitHub-Specific Use Cases

Perfect README Structure

# Project Name

![Logo](logo.png)

[![Build Status](badge.svg)](link)
[![License](license-badge.svg)](LICENSE)

## 🚀 Features

- Feature 1
- Feature 2
- Feature 3

## 📦 Installation

```bash
npm install project-name
```

## 📖 Usage

```javascript
import { Something } from 'project-name';
```

## 🤝 Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

## 📝 License

MIT © [Your Name](https://github.com/yourusername)

Issue Templates

## Bug Report

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce:
1. Go to '...'
2. Click on '...'
3. See error

**Expected behavior**
What you expected to happen.

**Screenshots**
If applicable, add screenshots.

**Environment:**
- OS: [e.g. macOS 13.0]
- Browser: [e.g. Chrome 110]
- Version: [e.g. 2.0.1]

**Additional context**
Any other information about the problem.

Pull Request Template

## Description
Brief description of changes

Fixes #(issue number)

## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings generated

GFM vs Standard Markdown: Key Differences

Related Resources

• Markdown Formatter Tool - Test GFM syntax with live preview
• Markdown Table Generator Guide - Master GFM tables
• Markdown to HTML Converter - Export your GFM as HTML
• Technical Documentation Guide - Professional docs with markdown
• Markdown Editor Comparison - Find the best editor for GFM

Frequently Asked Questions

Can I use GFM outside of GitHub?

Yes! Many platforms support GFM: GitLab, Bitbucket, Discord, Reddit, Slack, and more. However, features like @mentions and #issue-references are GitHub-specific. Use our Markdown Formatter to test compatibility.

Do task lists work in standard markdown?

No, task lists (- [ ] syntax) are a GFM extension. They'll render as plain text in standard markdown parsers.

How do I find all emoji shortcodes?

GitHub has hundreds of emoji. See the official emoji cheat sheet for a complete list, or use our Text Obfuscator for emoji-based text encoding.

Can I use HTML in GitHub markdown?

Yes, but with restrictions. GitHub sanitizes HTML for security. You can use safe tags like <details>,<summary>, <img>, <table>, but not <script>or inline JavaScript.