GitHub-Flavored Markdown (GFM): Complete Syntax Guide

If you've ever written a README, an npm package description, or a chat message on a developer platform, you've almost certainly used GitHub-Flavored Markdown (GFM) — even if you didn't know the name. GFM is the dialect of Markdown that GitHub built on top of the CommonMark standard, adding a handful of widely-loved extensions that have since become the de facto way developers format text on the web. This guide covers every GFM feature with copy-paste examples, explains why GFM matters beyond GitHub itself, and shows you how to preview it accurately.

For a quick at-a-glance reference covering all of Markdown (not just the GFM extras), bookmark the Markdown cheat sheet.

What is GitHub-Flavored Markdown?

Plain Markdown is defined by two things: the original 2004 spec by John Gruber, and CommonMark, the rigorous, test-driven standard that most modern parsers follow. CommonMark is strict and predictable, but deliberately minimal — it leaves out features people kept asking for, like tables and task lists.

GitHub Flavored Markdown (GFM) is a strict superset of CommonMark. It takes the full CommonMark spec and layers on a small set of extensions that GitHub developed for its own use. The current GFM extensions are:

• Tables
• Task list items (checkboxes)
• Strikethrough
• Autolink literals (bare URLs and emails become links)
• Disallowed raw HTML (a safelist-based HTML filter)

Because GitHub is where so much documentation lives, these extensions spread everywhere. The same renderer powers npm readmes, static-site generators, chat apps, and documentation tools — so learning GFM is arguably more useful today than learning raw CommonMark.

The mental model: CommonMark is the foundation; GFM is CommonMark plus five well-defined extras. Anything valid in CommonMark is valid in GFM.

Tables

Tables are the headline GFM feature. You define a header row, a delimiter row of dashes, and data rows, all separated by pipes.

| Method | Path          | Description          |
| ------ | ------------- | -------------------- |
| GET    | `/users`      | List all users       |
| POST   | `/users`      | Create a new user    |
| DELETE | `/users/:id`  | Delete a user by id  |

Method	Path	Description
GET	/users	List all users
POST	/users	Create a new user
DELETE	/users/:id	Delete a user by id

You can also control column alignment by adding colons in the delimiter row (:---, :---:, ---:). Tables need a blank line before and after them, and literal pipes inside a cell must be escaped as \|.

Task lists

Task lists turn bulleted lists into interactive checkboxes on GitHub, and render as checkboxes (or [x] / [ ] markers) elsewhere. They're perfect for issue trackers, release notes, and README "roadmap" sections.

- [x] Parse frontmatter
- [x] Render GFM tables
- [ ] Add RSS feed
- [ ] Write integration tests

Renders as:

• Parse frontmatter
• Render GFM tables
• Add RSS feed
• Write integration tests

A few details worth knowing:

• The checkbox markers ([x] and [ ]) are case-insensitive for the checked state — [X] also works — but lowercase x is the convention.
• The space inside the brackets is required: [ ] is a task item, [] is not.
• Task lists work inside both bulleted (-) and ordered (1.) lists, though bullets are far more common.

Strikethrough

Wrap text in double tildes to strike it through. Useful for edits, deprecated notes, and the classic "wrong right" pattern in docs.

The old endpoint ~~`/api/v1/users`~~ is retired. Use `/api/v2/users` instead.

The old endpoint /api/v1/users is retired. Use /api/v2/users instead.

One subtlety: a single tilde does nothing. GFM requires exactly two tildes to open and close the strikethrough. If you need a literal double-tilde in your text (rare, but it happens in some math contexts), escape it: \~~.

Autolink literals

In original Markdown, only explicitly-wrapped URLs become links: <https://example.com> or [text](https://example.com). GFM adds autolink literals: it detects bare URLs and email addresses in your text and turns them into clickable links automatically.

Visit https://example.com or email [email protected] for help.

Visit https://example.com or email [email protected] for help.

This also applies to URLs inside a code span or code block — they'll be autolinked when the code block's language is text or unspecified, but left as-is inside syntax-highlighted code. It's a small touch, but it's why pasting a raw URL into a GitHub comment "just works."

Heads-up: autolinking uses a strict URL scheme check. example.com without https:// is not autolinked — it has to start with http://, https://, or www.. Email autolinking uses a separate RFC-compliant pattern.

Fenced code blocks with a language hint

Fenced code blocks come from CommonMark, but GFM adds the convention that the language name after the opening fence enables syntax highlighting. Almost every GFM renderer supports this.

```js
function greet(name) {
  return `Hello, ${name}!`;
}
```

function greet(name) {
  return `Hello, ${name}!`;
}

A few tips:

• You can use three or more backticks (or tildes) for the fence, as long as the open and close match. Backticks are far more common.
• The language hint is case-insensitive: js, javascript, and JavaScript all work.
• Use a fenced block with no language when you want monospaced text without any coloring — handy for ASCII diagrams and command output.

If you want to display literal triple-backticks inside a fenced block, wrap the outer block in a longer fence (four or more backticks), as in the example above.

Disallowed raw HTML

CommonMark lets you embed raw HTML anywhere. GFM keeps that, but adds a safelist-based filter that strips potentially dangerous tags and attributes — things like <script>, event handlers (onclick), and style attributes that could break layouts or run code. This is what makes it safe for GitHub to render user-submitted Markdown.

For everyday writing, the practical effect is small: most formatting tags you'd actually use (<sub>, <sup>, <details>, <br>) still work. But if you're surprised that a particular <script> or inline style vanished from your rendered readme, the HTML filter is why.

Feature-by-syntax summary

Feature	Syntax	CommonMark?
Tables	Pipe-separated rows + delimiter row	No
Task lists	- [x] / - [ ]	No
Strikethrough	~~text~~	No
Autolink literals	Bare URLs/emails auto-linked	No
Fenced code + lang	js …	Base only
Disallowed raw HTML	Safelist HTML filter	No
Headings, lists, etc.	Standard Markdown	Yes

Why GFM matters beyond GitHub

GFM long ago escaped GitHub's walls. Because the spec is open and the reference implementation is widely ported, the same dialect now powers:

• npm package readmes — every package page renders GFM.
• Documentation sites — Jekyll, Docusaurus, MkDocs-Material, VitePress, and most static-site generators default to GFM-aware renderers.
• Chat and collaboration tools — many developer-focused chat apps, issue trackers, and note apps accept GFM.
• README files everywhere — GFM has become the expected format for any README.md in a code repository.

That ubiquity means GFM is a transferable skill. Learn it once and your muscle memory carries across platforms — which is exactly why so many Markdown tutorials now teach GFM as the default rather than vanilla Markdown.

The flip side is that rendering varies by tool. A table that looks great on GitHub might collapse to plain text in a viewer that only implements CommonMark. Before you ship a GFM-heavy document, preview it in an environment that actually supports the extensions.

How to preview GFM accurately

The fastest way to confirm your Markdown will render the way you expect is to use a GFM-aware previewer. Paste your text into the MD viewer — it renders with full GFM support, so tables, task lists, strikethrough, and autolinks all display exactly as they would on GitHub.

From there, you can export the same source into other formats: publish a web page with Markdown to HTML when you need standalone markup, or produce a polished handout with Markdown to PDF for sharing offline.

Key takeaways

• GitHub-Flavored Markdown (GFM) is a strict superset of CommonMark plus five extensions: tables, task lists, strikethrough, autolink literals, and a safelist HTML filter.
• Task lists use - [x] / - [ ]; strikethrough uses ~~text~~; bare URLs autolink if they include a scheme or www..
• Fenced code blocks with a language hint (e.g. ```js) enable syntax highlighting across virtually all GFM renderers.
• GFM is the de facto Markdown dialect for npm, documentation sites, and README files — far beyond GitHub itself.
• Rendering varies by tool, so always preview in a GFM-aware viewer before publishing.

Write your next doc the GFM way — open the MD viewer, paste your Markdown, and see every extension render live.