GitHub Flavored Markdown (GFM)

CommonMark was created to make core Markdown syntax behave more consistently across different tools. Features such as headings, lists, links, emphasis, and inline code follow a defined specification.

GFM is based on the CommonMark specification and adds extensions that GitHub uses for documentation and collaborative development.

Some of the most commonly used GFM extensions include:

• Tables
• Task list items
• Strikethrough
• Extended automatic links
• Footnotes

Because GFM includes the CommonMark foundation, standard CommonMark syntax works on GitHub. The reverse is not always true: a renderer that supports only CommonMark may not recognize GFM-specific extensions.

If portability across different Markdown tools is important, rely mainly on CommonMark core syntax. If you're publishing primarily on GitHub or another compatible renderer, GFM's additional features can be useful.

For a closer look at the underlying standard, see the CommonMark Guide.

The table below is a quick overview. Each feature also has a dedicated guide with more detailed syntax and examples.

Fenced code blocks are part of the CommonMark foundation that GFM builds on. On GitHub, adding a language identifier to a code fence enables syntax highlighting:

```javascript
const message = "Hello, GitHub!";
```

See Markdown Code Blocks for complete examples.

GitHub provides extra behavior that people often associate with GFM. These features are useful on GitHub, but they should not automatically be treated as portable Markdown syntax.

@Mentions#

Typing @username can link to a GitHub user's profile and notify them.

Mentions are commonly used in Issues, Pull Requests, and Discussions to bring collaborators into a conversation.

Issue and Pull Request References#

A reference such as #25 can link to an issue or pull request in the current repository:

Fixed in #25

GitHub can also recognize cross-repository references:

owner/repository#25

These references connect related discussions without requiring a full URL.

Commit References#

GitHub can automatically link a recognized commit SHA to the relevant commit:

9fceb02

This is useful when discussing specific changes during code reviews or issue threads.

Repository Links#

Relative links are especially useful when linking between files in the same repository:

[Installation Guide](docs/installation.md)

Unlike hardcoded repository URLs, relative links keep working when the project is forked or viewed on a different branch. For full link syntax, see the link syntax reference.

HTML on GitHub#

GitHub supports a restricted subset of HTML in Markdown content. Elements such as <details>, <summary>, <kbd>, <sub>, <sup>, and <br> are useful when standard Markdown does not provide the formatting you need. For example, <details> and <summary> can create collapsible sections.

GitHub sanitizes HTML, so not every tag or attribute is allowed. See Markdown HTML for supported syntax and restrictions.

Some features appear often in GitHub documentation but are worth distinguishing from the core GFM extensions above.

Heading Links#

GitHub generates anchor links for headings, so you can link directly to a section of a README or document. For heading syntax and structure, see Markdown Headings.

Emojis#

GitHub supports standard Unicode emojis and also recognizes many emoji shortcodes:

:rocket: Project released
:white_check_mark: Tests passed
:warning: Review before deploying

For compatibility details and a larger shortcode reference, see Markdown Emojis.

GitHub provides the most complete and predictable environment for GitHub Flavored Markdown.

Outside GitHub, support depends on the Markdown parser and configuration a platform uses. Many Markdown editors, documentation tools, and static site generators support individual GFM-style features such as tables, task lists, or fenced code blocks.

However, feature support is not always identical. Footnotes, extended autolinks, emoji shortcodes, and other extensions may require additional configuration or plugins.

Before publishing the same Markdown file across multiple platforms, preview it with the renderer that will display it.

General Markdown problems — such as unclear link text or poorly structured content — are covered in the Common Markdown Mistakes guide. A few mistakes are specific to working with GFM.

Assuming Every Renderer Supports GFM#

Core Markdown syntax is widely supported, but GFM extensions are not guaranteed to work everywhere. Check the target platform before relying on tables, task lists, footnotes, or other extensions.

Forgetting the Language Identifier in Code Blocks#

A fenced code block works without a language identifier, but adding one enables syntax highlighting on GitHub:

```javascript
const total = 10;
```

Use the appropriate language identifier whenever syntax highlighting improves readability.

Treating Platform Features as Standard Markdown#

Features such as @mentions, issue references, and commit references depend on GitHub's platform behavior. They may not work when the same file is rendered elsewhere.

Overusing HTML#

HTML can solve formatting problems that Markdown cannot, but too much of it makes documentation harder to read and less portable. Use native Markdown syntax whenever it produces the same result.

The easiest way to understand GFM is to write its syntax and preview the result.

Use the Markdown Editor to test Markdown with live preview, or start with the README Generator to create a structured project README.