GitHub Flavored Markdown (GFM) — Tables, Task Lists, Alerts and More

Standard Markdown covers headings, lists, links, and emphasis — but the moment you write a README, open an issue, or review a pull request on GitHub, you are actually using GitHub Flavored Markdown (GFM). GFM extends the CommonMark specification with tables, task lists, strikethrough, autolinks, syntax-highlighted code fences, footnotes, and alert boxes. This guide walks through every GFM extension with copy-paste examples, and explains where each one works.

Tables and Alignment Syntax

Tables are the most-used GFM extension. Columns are separated by pipes, and the second row of hyphens marks the header. Colons in that separator row control alignment: :--- aligns left, :---: centers, and ---: aligns right.

| Feature       | Status   | Coverage |
| :------------ | :------: | -------: |
| Login         | Done     |      95% |
| Payments      | Review   |      80% |
| Notifications | Planned  |       0% |

You do not need to line up the pipes perfectly — GitHub renders ragged tables fine — but aligned source is much easier to review in a diff. Outer pipes are optional, and you can use inline formatting (bold, code, links) inside cells. What you cannot do is merge cells or add multi-line content; for that you need HTML or a different structure.

Task Lists and Strikethrough

Task lists turn bullet items into checkboxes. In issues and pull requests they are interactive — clicking the checkbox updates the source, and GitHub shows a progress count like "3 of 5 tasks" on the issue card.

- [x] Write the migration script
- [x] Add unit tests
- [ ] Update the API docs
- [ ] Deploy to staging

Use ~~strikethrough~~ for text that is no longer valid.

Strikethrough uses double tildes: ~~old plan~~ renders with a line through it. It is useful for showing superseded decisions without deleting the history of the discussion.

Autolinks, Mentions, and Issue References

GFM automatically converts several plain-text patterns into links, no bracket syntax required:

• URLs — pasting https://dev-brains-ai.com becomes a clickable link automatically
• @mentions — typing @username links to a profile and notifies that person or team
• Issue and PR references — #42 links to issue or PR number 42 in the same repo; owner/repo#42 works across repositories
• Commit SHAs — pasting a full or short commit hash links to that commit
• Closing keywords — writing "Fixes #42" in a PR description automatically closes issue 42 when the PR merges

These references are the glue of a GitHub workflow: they build a cross-linked trail between bugs, fixes, and releases without any manual effort.

Code Fences with Syntax Highlighting

Fenced code blocks use three backticks. Add a language identifier immediately after the opening fence and GitHub applies full syntax highlighting:

```javascript
const total = items.reduce((sum, item) => sum + item.price, 0);
```

```diff
- const timeout = 3000;
+ const timeout = 10000;
```

GitHub supports hundreds of languages via Linguist — js, python, sql, bash, json, yaml, and more. The diff language is especially handy in PR discussions: lines starting with a plus render green and lines starting with a minus render red.

Footnotes and Alerts

Footnotes let you add references without cluttering the main text. Alerts (also called admonitions) render as colored callout boxes and are perfect for warnings in READMEs:

Here is a claim that needs a source.[^1]

[^1]: The footnote text appears at the bottom of the page.

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

> [!WARNING]
> Critical content demanding immediate attention.

Five alert types are supported: [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], and [!CAUTION]. Each renders with its own icon and color. Alerts are a GitHub-specific extension — other Markdown renderers will show them as plain blockquotes, so do not rely on them outside GitHub.

Where GFM Works (and Where It Does Not)

• README and docs files — tables, fences, footnotes, and alerts all render; task lists show as static checkboxes
• Issues and pull requests — everything works, and task lists plus mentions become interactive
• Discussions, wikis, and gists — full GFM support
• Commit messages — issue references link, but most formatting is not rendered in every view
• Outside GitHub — GitLab and Bitbucket support most GFM; static site generators vary, so test tables and footnotes before publishing

When in doubt, preview before you publish. A live previewer such as the free Dev Brains AI Markdown Previewer shows exactly how tables, task lists, and code fences will render as you type.

Frequently Asked Questions