What is GitHub Flavored Markdown?

CommonMark plus five additions: tables, task lists, strikethrough, automatic linking of bare URLs, and a list of raw HTML tags that are filtered out. GitHub layers more on top of that — alerts, mentions, emoji shortcodes, maths and Mermaid diagrams — which are GitHub features rather than parts of the GFM spec.

How do I make a table in a README?

Pipes for the cells and a row of dashes under the header, which is required. Colons in that row set alignment. Tables cannot nest and a cell cannot contain a blank line, so use for a line break inside one.

What are GitHub alerts?

Blockquotes that start with [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] render as coloured callouts with an icon. They are GitHub-only — anywhere else they render as an ordinary quote with a bracketed word at the top.

How do I add a checkbox?

A list item of the form - [ ] for unticked and - [x] for ticked. In an issue or pull request description they are clickable, and GitHub shows a progress count. In a README they render as static boxes.

What HTML does GitHub allow?

Presentational and structural tags survive — u, ins, mark, kbd, sub, sup, details, summary, dl, img with a width. Anything that can execute or load is removed: script, style, iframe, form, event handlers, and style attributes. This is why align="center" works and text-align in a style attribute does not.

Where does GitHub not render Markdown?

Commit messages, release tag names, and most plain-text fields show the characters as typed. Markdown renders in files ending .md, in issue and pull request bodies and comments, in discussions, in wikis, and in release notes.

GitHub Markdown

GitHub Flavored Markdown is CommonMark plus tables, task lists, strikethrough and automatic links — and GitHub itself adds alerts, mentions, emoji, maths and diagrams on top. Everything it renders, and everything it quietly removes, is below.

Edit this — the preview is standard Markdown, so compare it with GitHub

Markdown

Result

Runs entirely in this tab. Open the full editor to work on a real document.

The preview renders standard Markdown. Where it disagrees with GitHub — the alert above is the clearest case — that gap is the GitHub-only part.

What GFM adds to CommonMark

Feature	Syntax	Notes
Tables	`\| A \| B \|`	Separator row required
Task list	`- [ ]` `- [x]`	Clickable in issues and PRs
Strikethrough	`~~struck~~`	Two tildes
Autolink	`https://example.com`	Bare URLs link themselves
Footnote	`[^1]`	Collected at the foot of the page

The spec also lists raw HTML tags that are always filtered out. That is a part of GFM most summaries leave out, and it is the reason a <script> in a README does nothing.

Alerts

A blockquote whose first line is a bracketed keyword becomes a coloured callout:

> [!NOTE]
> Useful information.

> [!WARNING]
> Something that could go wrong.

Five keywords: NOTE, TIP, IMPORTANT, WARNING and CAUTION, each with its own colour and icon. This is the closest GitHub gets to coloured text, and it is the answer to most of the reasons people go looking for it.

Alerts are GitHub-only. Everywhere else the keyword renders as literal text at the top of a quote, which is untidy but not broken — worth knowing if the same file is published elsewhere.

Task lists

- [x] Written
- [ ] Reviewed
- [ ] Shipped

In an issue or pull request body, these render as real checkboxes that anyone with write access can tick, and GitHub shows the count in the issue list. In a README they are static. Nesting works with the usual list indentation, and a parent's box does not tick itself when its children do.

Collapsible sections

<details>
  <summary>Show the full log</summary>

  Content here, with blank lines so the **Markdown** inside parses.

</details>

Plain HTML rather than Markdown, and the most useful thing HTML adds to a README: long output, alternative install instructions and FAQ answers all collapse out of the way. The blank lines matter — without them the Markdown inside stays literal.

Images

The Markdown form is ![alt text](path.png), and a relative path resolves against the file's own location in the repository. Two things Markdown cannot do, and HTML can:

<img src="logo.png" alt="Logo" width="200">

<p align="center"><img src="logo.png" alt="Logo" width="200"></p>

Sizing and centring both need the tag. GitHub also honours a <picture> element with a prefers-color-scheme media query, which is how projects show a different logo in dark mode.

GitHub-only conveniences

Mentions and references — @username, #123 for an issue or pull request in the same repository, owner/repo#123 across repositories, and a bare commit SHA all become links.
Emoji shortcodes — :tada: and friends render as emoji. The literal character works too and is more portable.
Maths — $x^2$ inline and $$…$$ as a block, rendered with LaTeX syntax.
Mermaid diagrams — a code fence with mermaid as its language renders as a diagram rather than as code.
A contents dropdown — generated from the headings at the top-right of any rendered file. Nothing goes in the file.

What GitHub strips

Every README is untrusted input, so the HTML passes through a sanitiser first. The pattern is that presentation stays and anything that can execute or load goes.

Survives	Removed
`<u> <ins> <mark> <kbd>`	`<script> <style>`
`<sub> <sup> <br>`	`style="…"` attributes
`<details> <summary>`	`onclick` and other handlers
`<dl> <dt> <dd>`	`<iframe> <form> <object>`
`align="center"`	`<meta> <link>`

That last row is the one that surprises people: the attribute deprecated twenty years ago works, and its modern CSS replacement does not.

Where Markdown renders, and where it does not

It renders in .md files, issue and pull request bodies and comments, discussions, wikis, and release notes. It does not render in commit messages, tag names, or repository descriptions — those show the characters exactly as typed, which is why a bulleted commit message looks like a bulleted commit message and not a list.

Common questions

What is GitHub Flavored Markdown?: CommonMark plus five additions: tables, task lists, strikethrough, automatic linking of bare URLs, and a list of raw HTML tags that are filtered out. GitHub layers more on top of that — alerts, mentions, emoji shortcodes, maths and Mermaid diagrams — which are GitHub features rather than parts of the GFM spec.
How do I make a table in a README?: Pipes for the cells and a row of dashes under the header, which is required. Colons in that row set alignment. Tables cannot nest and a cell cannot contain a blank line, so use <br> for a line break inside one.
What are GitHub alerts?: Blockquotes that start with [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] render as coloured callouts with an icon. They are GitHub-only — anywhere else they render as an ordinary quote with a bracketed word at the top.
How do I add a checkbox?: A list item of the form - [ ] for unticked and - [x] for ticked. In an issue or pull request description they are clickable, and GitHub shows a progress count. In a README they render as static boxes.
What HTML does GitHub allow?: Presentational and structural tags survive — u, ins, mark, kbd, sub, sup, details, summary, dl, img with a width. Anything that can execute or load is removed: script, style, iframe, form, event handlers, and style attributes. This is why align="center" works and text-align in a style attribute does not.
Where does GitHub not render Markdown?: Commit messages, release tag names, and most plain-text fields show the characters as typed. Markdown renders in files ending .md, in issue and pull request bodies and comments, in discussions, in wikis, and in release notes.