GitHub Flavored Markdown (GFM): The Complete Syntax Guide

What is GitHub Flavored Markdown

Plain Markdown, as originally specified, is surprisingly limited. It has headings, lists, code blocks, and links — but no tables, no task lists, no strikethrough. Real-world writing needs more. GitHub Flavored Markdown (GFM) is the set of extensions that filled those gaps, and it has become the de facto Markdown of the modern web. README files, documentation sites, issue trackers, chat tools, and most Markdown viewers expect GFM.

If you write Markdown today, you are almost certainly writing GFM. Understanding its extensions — and confirming your viewer supports them — is the difference between documents that render beautifully and documents that half-render. You can test any snippet below in a Markdown viewer that supports full GFM.

This guide covers every GFM extension with copy-paste examples and notes on what to watch for.

Tables

Tables are the GFM feature people reach for first. They render as real HTML tables, not pipe text.

| Feature | Plain MD | GFM |
| --- | :--- | :---: |
| Tables | ❌ | ✅ |
| Task lists | ❌ | ✅ |
| Strikethrough | ❌ | ✅ |

The colons in the separator row control alignment: :--- left, ---: right, :---: center. Keep tables to a clean grid — GFM does not support merged or nested cells.

Always leave a blank line before and after a table. Without it, the table can merge into the surrounding paragraph and fail to render.

Task lists

Task lists turn bullet items into checkboxes. They are perfect for tracking steps in a README or an issue.

- [x] Set up the project
- [x] Write the docs
- [ ] Ship the release
- [ ] Collect feedback

Checked items render with a filled checkbox; unchecked items render empty. Task lists work inside both bulleted and numbered contexts, though they are most readable as bullets.

Strikethrough

Strikethrough is simple but useful for showing edits or marking obsolete content.

This feature is ~~deprecated~~ being replaced.

Wrap text in double tildes (~~like this~~) and it renders with a line through it.

Autolinks and code

GFM autolinks bare URLs and email addresses — you do not need angle brackets or Markdown link syntax.

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

Inside code spans and code blocks, GFM disables Markdown parsing, so you can show raw syntax without escaping:

Use the `||` operator to merge, not `+`.

```js
const merged = [...a, ...b];
```

For fenced code blocks, you can add a language tag for syntax highlighting, and you can use three or more backticks (or tildes) to nest fenced blocks.

Headings and the document outline

GFM headings create a real document outline. Use them in order and the result is a navigable, accessible document.

# Document title (H1)
## Section (H2)
### Subsection (H3)

Two habits keep outlines clean: use exactly one H1 per document as the title, and do not skip levels (jumping from H2 to H4 breaks the hierarchy that screen readers and table-of-contents tools rely on).

Lists and nesting

GFM handles ordered and unordered lists, and nests them with indentation.

1. First step
2. Second step
   - A sub-item
   - Another sub-item
3. Third step

Keep nesting shallow — two levels is usually enough — and separate list items from adjacent paragraphs with a blank line so the list renders as a list rather than running into body text.

Blockquotes

Blockquotes call out notes, warnings, or quoted material.

> This is a blockquote.
> It can span multiple lines.

They render with a visual indent and are a clean way to highlight callouts without resorting to bold shouting.

What "full GFM support" really means

Not every Markdown viewer supports every GFM feature. A weak renderer will show raw pipes instead of a table, or ignore task-list checkboxes. When you pick a viewer or converter, confirm it handles all of the following:

A Markdown viewer that supports full GFM renders every one of these correctly, which is why GFM support is the single most important feature to check.

Writing GFM that converts cleanly

GFM is also the best source format for conversion. The same .md file can become HTML for a website, PDF for a deliverable, or Word for review — and the GFM features survive each export:

• Tables stay tables in Markdown to HTML and Markdown to PDF
• Task lists render in Markdown to Word
• Code blocks keep their formatting everywhere

Write once in GFM, and your content is ready for any destination.

Try GFM now

The fastest way to learn GFM is to write some and see it render. Open the Markdown viewer, paste any snippet from this guide, and watch tables, task lists, and strikethrough come to life — all rendered locally in your browser with full GitHub Flavored Markdown support.