GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown, commonly abbreviated as GFM, is the Markdown dialect used across GitHub.

Unlike the original Markdown created by John Gruber, GFM includes several extensions that make technical documentation easier to write and easier to read.

Today, many documentation platforms, static site generators, note-taking applications, and Markdown editors support GFM because of its simplicity, consistency, and broad compatibility.

GitHub Markdown and GitHub Flavored Markdown are closely related but serve different purposes. GitHub Markdown focuses on writing and formatting content on GitHub, while GitHub Flavored Markdown (GFM) defines the extended syntax that GitHub supports. If you're looking for README workflows and repository documentation, see the GitHub Markdown guide. For Markdown fundamentals, start with Markdown Basics.

Standard Markdown provides the core formatting syntax used across most Markdown implementations, including:

• Headings
• Paragraphs
• Lists
• Links
• Images
• Blockquotes
• Inline code
• Code blocks

GitHub Flavored Markdown builds on this foundation by adding features designed for technical documentation, software development, and collaboration without changing the core Markdown syntax.

Every valid standard Markdown document is largely compatible with GFM, but documents that use GFM-only features require a parser that supports GitHub Flavored Markdown.

For most documentation projects, GitHub Flavored Markdown is the preferred choice because it remains compatible with standard Markdown while adding practical features such as tables, task lists, footnotes, and automatic URL linking.

If you need the core Markdown rules that work across different platforms, see the Markdown Syntax guide. If you're writing documentation specifically for GitHub repositories, README files, or Wikis, GFM is generally the better option.

GitHub Flavored Markdown (GFM) is built on the CommonMark specification, but the two are not the same.

CommonMark defines a standardized way to parse and render core Markdown syntax consistently across different applications. Its goal is to eliminate the inconsistencies found in early Markdown implementations.

GitHub Flavored Markdown follows the CommonMark specification and extends it with additional features that improve technical writing and collaborative workflows.

These extensions include:

• Tables
• Task lists
• Strikethrough
• Automatic URL linking
• Footnotes
• Syntax-highlighted fenced code blocks
• Heading anchors
• Emoji support

In simple terms:

• CommonMark defines the standard Markdown behavior.
• GitHub Flavored Markdown (GFM) implements CommonMark and adds developer-focused extensions.

This means every Markdown renderer that supports GFM also supports the CommonMark core syntax, but a CommonMark-only renderer may display GitHub-specific features such as task lists or footnotes as plain text instead of rendering them.

If portability across many Markdown engines is your priority, write using the CommonMark core syntax. If you're publishing documentation on GitHub or platforms that support GFM, you can safely use its extended features.

💡 Deep dive: Read the complete CommonMark Guide for what the specification covers, CommonMark compliance, and how to write portable Markdown.

Table support is one of the most useful GitHub Flavored Markdown extensions because it lets you organize structured information that would otherwise be difficult to scan in plain text.

Tables are commonly used for:

• Feature comparisons
• API documentation
• Configuration references
• Version compatibility
• Browser support
• Command references
• Release notes

💡 Deep dive: Read the complete Markdown Tables guide for syntax, alignment, GitHub compatibility, limitations, and best practices.

| Framework | Language |
|-----------|----------|
| React | JavaScript |
| Laravel | PHP |
| Django | Python |

Output

GitHub renders Markdown tables as responsive HTML tables, making them much easier to read than plain text lists when presenting structured information.

GitHub Flavored Markdown supports interactive task lists using checkbox syntax. They are one of the most popular GFM extensions because they help track progress directly inside documentation and collaboration workflows.

💡 Deep dive: Read the complete Markdown Task Lists guide for nested checklists, mixed lists, GitHub interactive checkboxes, and platform compatibility.

- [x] Repository created
- [x] README completed
- [ ] Documentation finished
- [ ] Release published

Output

Task lists work in:

• README files
• Issues
• Pull Requests
• Discussions
• GitHub Projects

Task lists make project status easy to understand at a glance and are widely used for release planning, issue tracking, documentation checklists, and development workflows.

GitHub Flavored Markdown supports fenced code blocks with language identifiers, allowing GitHub to automatically apply syntax highlighting for hundreds of programming languages.

💡 Deep dive: Read the complete Markdown Code Blocks guide for fenced-block syntax, language identifiers, and copy-friendly examples.

```javascript
function hello() {
  console.log("Hello World");
}
```

GitHub automatically highlights supported languages including:

• JavaScript
• TypeScript
• Python
• PHP
• Java
• Go
• Rust
• C#
• C++
• HTML
• CSS
• SQL
• JSON
• YAML
• Bash

Syntax highlighting improves readability, reduces mistakes when copying code, and makes installation guides, tutorials, and API documentation much easier to follow.

GitHub automatically detects plain web addresses and converts them into clickable hyperlinks without requiring Markdown link syntax.

https://github.com

Output

You can also create descriptive links. See Markdown Links for inline, reference, and relative link syntax.

[GitHub Documentation](https://docs.github.com)

Output

Although automatic links are convenient, descriptive link text is usually easier to read because it tells readers where the link goes before they click it.

GitHub Flavored Markdown supports strikethrough formatting, making it easy to indicate completed work, deprecated features, outdated information, or text that is no longer applicable.

~~Deprecated feature~~

Output

Strikethrough is commonly used in release notes, issue discussions, documentation updates, and changelogs where readers benefit from seeing what has changed without removing the original text.

GitHub Flavored Markdown supports both Unicode emojis and GitHub emoji shortcodes, allowing developers to add visual cues without affecting readability.

:rocket:

:tada:

:fire:

:white_check_mark:

:warning:

Output

Emojis are commonly used in README files, release notes, issue templates, and documentation to highlight important information, indicate status, or make long pages easier to scan.

💡 Deep dive: Read the complete Markdown Emojis guide for Unicode vs shortcodes, platform compatibility tables, and README examples.

GitHub Flavored Markdown supports footnotes using the standard reference-and-definition syntax, making it easy to add citations, references, and supplementary information without interrupting the main content.

💡 Deep dive: Read the complete Markdown Footnotes guide for numbered and named references, multiple footnotes, and platform compatibility.

Markdown supports footnotes.[^1]

[^1]: This is a GitHub Flavored Markdown feature.

Footnotes are especially useful for technical documentation, research notes, specifications, and long-form guides where additional context should remain available without distracting from the main content.

While the previous sections cover GFM syntax that many Markdown tools support, GitHub also provides several platform-specific features that are unique to the GitHub ecosystem.

These features work across repositories, Issues, Pull Requests, Discussions, and many other GitHub interfaces, helping teams collaborate more efficiently.

@Mentions#

You can notify another GitHub user by mentioning their username.

@username

GitHub automatically creates a link to the user's profile and sends them a notification.

Mentions are commonly used to request reviews, assign work, answer questions, and notify collaborators during project discussions.

Issue and Pull Request References#

Reference an issue or pull request using its number.

#25

Or reference another repository.

owner/repository#25

GitHub automatically converts these references into clickable links.

Cross-references make it easier to connect related Issues, Pull Requests, and discussions, giving contributors additional context without manually copying URLs.

Commit References#

You can reference commits using their SHA.

9fceb02

GitHub links directly to the referenced commit, making it easier to discuss code changes.

Commit references provide a convenient way to discuss specific code changes during reviews, debugging, and release planning.

Relative Links#

One of the biggest advantages of GitHub Markdown is support for relative links.

💡 Deep dive: Read the complete Markdown Links guide for relative paths, reference links, and email links.

[Installation Guide](docs/installation.md)

[API Documentation](docs/api.md)

Relative links are recommended for internal documentation because they continue working when repositories are forked, cloned locally, or viewed from different branches.

Heading Anchors#

GitHub automatically generates anchor links for headings.

See Markdown Headings for hierarchy rules, anchor links, and README structure.

Example:

## Installation

can be linked as:

[Jump to Installation](#installation)

Heading anchors improve navigation within long README files and documentation by allowing readers to jump directly to specific sections.

Supported HTML Elements#

Although GitHub Flavored Markdown covers most formatting needs, GitHub also supports a safe subset of HTML for layouts and formatting that Markdown cannot achieve on its own.

💡 Deep dive: Read the complete Markdown HTML guide for supported tags, security restrictions, and advanced formatting.

Commonly used tags include:

• <details>
• <summary>
• <kbd>
• <sub>
• <sup>
• <br>

Example:

<details>
<summary>Installation Steps</summary>

Run:

npm install

</details>

Output

The <details> element is widely used in README files to create expandable sections for installation instructions, FAQs, troubleshooting steps, and advanced configuration without making the page unnecessarily long.

Although GitHub introduced GitHub Flavored Markdown (GFM), it is now supported by many documentation tools, static site generators, note-taking applications, and Markdown editors.

Popular platforms include:

• GitHub
• GitHub Enterprise
• GitHub Pages
• Obsidian
• MkDocs
• Docusaurus
• Hugo
• Jekyll
• VS Code Markdown Preview (with supported extensions)
• Many online Markdown editors

Support for every GFM feature depends on the Markdown engine and configuration used by each platform. Features such as tables and fenced code blocks are widely supported, while extensions like footnotes may require additional plugins or enabled extensions.

Because GFM has become the de facto standard for technical documentation, learning it helps you write Markdown that works across a wide range of developer tools and publishing platforms.

Good documentation is not just about using the correct syntax—it is about making information easy to read, navigate, and maintain over time.

These best practices will help you create clearer README files, project documentation, and technical guides while taking full advantage of GitHub Flavored Markdown.

Organize Content with Headings#

Use a logical heading hierarchy throughout your documentation. See Markdown Headings for hierarchy rules and anchor links.

# Project Name

## Features

## Installation

## Usage

## Configuration

## Contributing

## License

Well-structured headings improve readability and allow GitHub to generate useful heading anchors.

Prefer Relative Links#

When linking files inside your repository, use relative paths instead of full GitHub URLs.

Recommended:

[Installation Guide](docs/installation.md)

Instead of:

https://github.com/username/project/blob/main/docs/installation.md

Relative links continue working even if the repository is forked or cloned locally.

Write Descriptive Link Text#

Instead of using generic text like Click here, use descriptive links.

Read the Installation Guide

This improves accessibility and helps users understand where the link leads.

Keep Code Examples Small#

Include short, focused examples instead of large code dumps.

Good documentation explains concepts using simple examples that readers can quickly understand and copy.

Use Syntax Highlighting#

Always specify the programming language for fenced code blocks. See Markdown Code Blocks for language identifiers and supported languages.

```bash
npm install
npm run dev
```

This enables GitHub's syntax highlighting and makes code easier to read.

Add Screenshots#

Visual documentation is often easier to understand than text alone. See Markdown Images for paths, alt text, and GitHub asset URLs.

Common examples include:

• Dashboard previews
• Application screenshots
• CLI output
• Architecture diagrams
• Workflow illustrations

Images make README files significantly more engaging.

Use Tables for Structured Data#

Instead of writing long paragraphs, use tables for structured information. See Markdown Tables for alignment and formatting.

Examples:

• Feature comparisons
• Browser compatibility
• API parameters
• Configuration options
• Version support

Tables are easier to scan and improve the overall reading experience.

Keep Documentation Updated#

Outdated documentation quickly becomes a source of confusion.

Whenever your project changes, review your README and supporting documentation to ensure that installation instructions, commands, screenshots, links, and examples still reflect the current version.

Accurate documentation builds trust, reduces support requests, and provides a better experience for contributors and users.

Even experienced developers occasionally make formatting mistakes that reduce readability or prevent GitHub-specific features from rendering correctly.

Review these common issues before publishing your documentation.

Confusing Standard Markdown with GFM#

Many tutorials teach basic Markdown but omit GitHub-specific features.

Remember that GitHub Flavored Markdown supports additional syntax such as:

• Tables
• Task Lists
• Strikethrough
• Footnotes
• Automatic URL Linking

If you're writing documentation for GitHub, take advantage of GFM features where they improve readability. If your content must work across many Markdown engines, verify that your target platform supports those extensions before using them.

Forgetting Language Identifiers#

Incorrect:

```
console.log("Hello");
```

Correct:

```javascript
console.log("Hello");
```

Adding the language enables syntax highlighting and improves readability. See Markdown Code Blocks for supported languages.

Using Absolute GitHub Links#

Instead of:

https://github.com/username/project/blob/main/docs/setup.md

Use:

[Setup Guide](docs/setup.md)

Relative links continue working when the repository is cloned or forked.

Writing Large Walls of Text#

Avoid long paragraphs without headings.

Instead:

• Break content into sections.
• Use lists where appropriate.
• Add tables for structured information.
• Include examples after explanations.

Readable documentation encourages users to continue reading.

Ignoring Accessibility#

Always provide descriptive alt text for images. See Markdown Images for best practices.

Instead of:

![](dashboard.png)

Use:

![Project Dashboard](dashboard.png)

Accessible documentation benefits all users and follows good documentation practices.

Overusing HTML#

GitHub supports HTML, but Markdown should remain your primary formatting language.

Only use HTML elements such as <details> or <kbd> when Markdown cannot achieve the desired result. See Markdown HTML for supported tags and security restrictions.

Keeping documentation mostly in Markdown improves portability across different editors and platforms.

Not Testing Markdown#

Before publishing your documentation, always preview the rendered output instead of relying only on the raw Markdown source.

Check that:

• Tables render correctly
• Images load properly
• Internal and external links work
• Code blocks use the correct syntax highlighting
• Heading anchors navigate correctly
• Task lists and footnotes render as expected

Previewing your documentation helps catch formatting issues before your readers do. Use the Markdown Editor to verify rendering across common GitHub Flavored Markdown features before publishing.

The fastest way to become comfortable with GitHub Flavored Markdown is to build a real README while previewing the rendered output.

Open the Markdown Editor to experiment with tables, task lists, footnotes, syntax-highlighted code blocks, and HTML elements in real time. Keep the Markdown Cheat Sheet nearby for quick syntax lookup, or use the README Generator to create a solid starting point for your project documentation.

Try building a README that includes:

• A clear title and description with heading anchors
• A feature comparison table
• A release checklist with task lists
• Syntax-highlighted code blocks with language identifiers
• At least one footnote for additional context
• A collapsible <details> section for optional setup steps

Summary#

GitHub Flavored Markdown (GFM) extends the CommonMark specification with features that make technical documentation easier to write, maintain, and collaborate on.

In this guide, you learned:

• What GitHub Flavored Markdown is
• How GFM differs from Standard Markdown and CommonMark
• Tables, task lists, syntax-highlighted code blocks, and other GFM extensions
• GitHub-specific features such as mentions, issue references, and relative links
• HTML support, heading anchors, and documentation best practices
• Common formatting mistakes to avoid

Whether you're creating a README, maintaining project documentation, or contributing to open-source software, understanding GitHub Flavored Markdown will help you write documentation that is clearer, more maintainable, and compatible with modern developer workflows.