GitHub Flavored Markdown (GFM): Everything You Need to Know

GFM is a superset of standard Markdown (specifically, CommonMark). Everything in CommonMark works in GFM, plus these additions:

• Tables with alignment support
• Task lists (checkboxes)
• Strikethrough text
• Autolinked URLs and references
• Fenced code blocks with syntax highlighting
• Emoji shortcodes
• Footnotes
• Alerts/admonitions

The GFM spec is maintained by GitHub and is formally defined at github.github.com/gfm. Let's walk through each feature.

GFM tables use pipes (|) and dashes (-) to create structured data. The separator row between the header and body is required:

| Feature     | Supported | Notes              |
|-------------|:---------:|-------------------:|
| Tables      | ✅ Yes    | Alignment support  |
| Task lists  | ✅ Yes    | Interactive on GH  |
| Footnotes   | ✅ Yes    | Added in 2021      |

Column Alignment

Use colons in the separator row to control text alignment:

| Left     | Center    | Right     |
|:---------|:---------:|----------:|
| aligned  | aligned   | aligned   |

• :--- = left-aligned (default)
• :---: = center-aligned
• ---: = right-aligned

For a complete deep-dive on table syntax and formatting, see our Markdown Tables guide.

Task lists render as interactive checkboxes on GitHub. They're widely used in issues and pull requests to track progress:

- [x] Design the database schema
- [x] Implement the API endpoints
- [ ] Write integration tests
- [ ] Update documentation
- [ ] Deploy to production

On GitHub, collaborators can click the checkboxes directly in issues to toggle them — you don't need to edit the Markdown. GitHub also shows a progress bar at the top of the issue when task lists are present (e.g., "3/5 tasks complete").

GFM adds strikethrough support using double tildes:

~~This text is struck through.~~

Strikethrough is useful for showing changes, marking deprecated items, or adding humor to discussions. It's not part of the original Markdown spec or CommonMark — it's a GFM extension.

While fenced code blocks exist in CommonMark, GFM adds syntax highlighting. Specify the language after the opening backticks:

```typescript
interface User {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
}

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

GitHub supports syntax highlighting for hundreds of languages, including all major programming languages, configuration formats (YAML, TOML, JSON), shell scripts, SQL, and even specialized formats like Dockerfile, GraphQL, and Terraform.

Useful Language Identifiers

```javascript   ```python      ```rust
```typescript   ```java        ```go
```bash         ```sql         ```yaml
```json         ```html        ```css
```diff         ```dockerfile  ```graphql
```markdown     ```shell       ```toml

GFM automatically converts certain text patterns into clickable links:

• URLs — https://example.com becomes a clickable link automatically.
• Issue references — #123 links to issue/PR #123 in the same repo.
• Cross-repo references — owner/repo#123 links to an issue in another repo.
• User mentions — @username creates a mention that notifies the user.
• Commit SHAs — Full or short commit hashes (7+ chars) link to that commit.

Fixes #42
See also: facebook/react#12345
cc @octocat
Related commit: a5c3785ed8

These autolinks are incredibly powerful for development workflows — they create a web of connections between issues, PRs, commits, and people.

GFM supports emoji shortcodes — text identifiers surrounded by colons that render as emoji:

:rocket:     → 🚀
:bug:        → 🐛
:sparkles:   → ✨
:warning:    → ⚠️
:tada:       → 🎉
:thumbsup:   → 👍
:100:        → 💯

GitHub maintains a full list of supported shortcodes. You can also use native Unicode emoji directly — just paste them into your Markdown.

GitHub added footnote support in 2021. They're great for adding references without cluttering the main text:

Markdown was created by John Gruber[^1] in 2004.

The CommonMark spec[^2] resolved many ambiguities
in the original specification.

[^1]: John Gruber's blog: https://daringfireball.net
[^2]: CommonMark specification: https://commonmark.org

Footnotes render as superscript numbers in the text, with the full references listed at the bottom of the document. Clicking a footnote scrolls to the reference, and clicking the back arrow returns to the footnote marker.

GitHub recently added support for styled alert blocks using a special blockquote syntax:

> [!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.

Each alert type renders with a distinct color and icon — blue for notes, green for tips, purple for important, yellow for warnings, and red for caution. They're excellent for documentation and README files where you need certain information to stand out.

GitHub renders Mermaid diagrams directly from code blocks, letting you create flowcharts, sequence diagrams, and more without external tools:

```mermaid
graph LR
    A[Write Markdown] --> B[Preview]
    B --> C{Looks good?}
    C -->|Yes| D[Export]
    C -->|No| A
```

Mermaid supports flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, pie charts, and more. It's a powerful way to include diagrams in your documentation that are version-controlled alongside your code.

Beyond the GFM spec, GitHub's renderer handles some additional niceties:

• Math expressions — Use $inline$ and $$block$$ syntax for LaTeX math rendering.
• GeoJSON/TopoJSON maps — Put GeoJSON in a code block with the geojson language identifier and GitHub renders an interactive map.
• STL 3D models — Upload .stl files and GitHub renders an interactive 3D viewer.
• CSV rendering — .csv files display as formatted tables automatically.

A few best practices for writing effective GFM:

• Use task lists in issues for tracking multi-step work. GitHub's project views recognize and display task progress.
• Reference issues and PRs with #123 syntax to create a connected paper trail.
• Add language identifiers to code blocks — always. Unhighlighted code is harder to read.
• Use alerts for documentation to highlight important information, breaking changes, and prerequisites.
• Write meaningful commit messages — if they reference issues (Fixes #42), GitHub automatically closes the issue when the PR merges.

For more on writing effective documentation, see our guide on how to write a README.md that developers actually read.