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 and flexibility.

For a practical introduction to Markdown fundamentals, start with Markdown Basics. For GitHub README workflows and repository documentation, see the GitHub Markdown guide.

Standard Markdown provides basic formatting features such as:

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

GitHub Flavored Markdown builds on those basics and adds modern documentation features.

Feature	Standard Markdown	GitHub Flavored Markdown
Tables	❌	✅
Task Lists	❌	✅
Syntax Highlighting	Limited	✅
Strikethrough	❌	✅
Footnotes	❌	✅
Auto URL Links	❌	✅
Heading Anchors	Limited	✅

For most projects, GitHub Flavored Markdown is the recommended choice.

See the complete Markdown Syntax reference for standard formatting rules and how they compare to extended Markdown features.

Many users confuse CommonMark with GitHub Flavored Markdown.

CommonMark is a standardized Markdown specification that defines how Markdown should be parsed consistently across platforms.

GitHub Flavored Markdown is an extension of CommonMark. It follows the CommonMark specification while adding GitHub-specific features for documentation and collaboration.

In simple terms:

• CommonMark defines the foundation.
• GitHub Flavored Markdown adds extra capabilities on top of it.

This is why every GFM document is largely compatible with CommonMark, but not every CommonMark parser supports all GitHub-specific features.

One of the biggest improvements over standard Markdown is table support.

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

Tables are commonly used for:

• Feature comparisons
• API documentation
• Configuration references
• Version compatibility
• Browser support
• Pricing comparisons

GitHub Flavored Markdown supports interactive task lists.

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

They are ideal for project planning and progress tracking.

GFM supports fenced code blocks with syntax highlighting.

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, especially in technical documentation.

GitHub automatically converts plain URLs into clickable links.

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

Descriptive links usually provide a better reading experience than raw URLs.

GitHub supports strikethrough formatting.

~~Deprecated feature~~

Output

Strikethrough is useful for completed tasks, deprecated features, and outdated information.

GitHub supports both Unicode emojis and emoji shortcodes.

:rocket:

:tada:

:fire:

:white_check_mark:

:warning:

Output

Emojis help make documentation more engaging while drawing attention to important information.

GitHub Flavored Markdown supports footnotes for citations and additional notes.

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 allow you to include extra information without interrupting the flow of your main content.

In addition to standard GFM syntax, GitHub provides several platform-specific features that make collaboration easier.

These features are available in repositories, issues, pull requests, discussions, and many README files.

@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.

This feature is widely used during code reviews and 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.

Commit References

You can reference commits using their SHA.

9fceb02

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

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 continue working even when repositories are cloned locally.

They are recommended for linking internal documentation.

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)

Anchor links improve navigation inside long README files and documentation.

Supported HTML Elements

GitHub Flavored Markdown allows several HTML elements when Markdown alone is not sufficient.

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 one of the most popular GitHub features because it creates expandable content without requiring JavaScript.

GitHub Flavored Markdown is supported in many places beyond GitHub itself.

Popular platforms include:

• GitHub
• GitHub Enterprise
• GitHub Pages
• VS Code Markdown Preview
• Obsidian
• MkDocs
• Docusaurus
• Hugo
• Jekyll
• Many online Markdown editors

Because GFM has become the de facto standard, learning it allows you to write documentation that works across numerous developer tools and platforms.

Following a few best practices will make your README files and documentation more professional, easier to maintain, and more useful for contributors.

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 causes confusion.

Whenever you release new features or update your project, review your README and documentation to ensure that installation steps, commands, screenshots, and examples remain accurate.

Keeping documentation current builds trust and improves the developer experience.

Even experienced developers occasionally make mistakes when writing GitHub Flavored Markdown. Avoiding these common issues will make your documentation cleaner and easier to maintain.

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 specifically for GitHub, prefer GFM features whenever they improve readability.

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 documentation, preview it in GitHub or a Markdown editor.

Check that:

• Tables render correctly
• Images load properly
• Links work
• Code blocks display as expected
• Heading anchors function correctly
• Task lists render properly

Previewing helps catch formatting issues before users see them. Open the Markdown Editor to verify rendering before you publish.

The best way to learn GitHub Flavored Markdown is by writing it yourself.

Open the Markdown Editor to experiment with tables, task lists, strikethrough, code blocks, footnotes, and HTML elements while previewing the rendered output in real time. Keep the Markdown Cheat Sheet nearby for quick syntax lookup.

To scaffold a professional README quickly, use the README Generator — then refine the Markdown with tables, task lists, and installation steps from this guide.

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

GitHub Flavored Markdown (GFM) is the modern standard for writing documentation on GitHub and many other developer platforms.

In this guide, you learned:

• What GitHub Flavored Markdown is
• GFM vs Standard Markdown
• GFM vs CommonMark
• Tables, task lists, and syntax-highlighted code blocks
• Automatic URL linking, strikethrough, emojis, and footnotes
• GitHub-specific features such as @mentions, issue references, and relative links
• HTML support and heading anchors
• Best practices and common mistakes
• Frequently asked questions

Whether you're creating a professional README, writing technical documentation, contributing to open-source projects, or building documentation websites, mastering GitHub Flavored Markdown will help you produce cleaner, more maintainable, and more professional documentation.

Continue learning Markdown with these guides:

Available now

• Markdown Basics — core concepts for beginners
• Markdown Cheat Sheet — quick syntax lookup
• Markdown Syntax — complete reference with examples
• Markdown Headings — document structure with H1–H6
• Markdown Paragraphs — blank lines and spacing
• Markdown Lists — ordered, unordered, nested, and task lists
• Markdown Links — inline, reference, and relative links
• Markdown Images — syntax, URLs, alt text, and GitHub paths
• Markdown Tables — syntax, alignment, and GitHub GFM
• Markdown Code Blocks — fenced blocks and syntax highlighting
• Markdown Blockquotes — syntax, nesting, and GitHub callouts
• Markdown Horizontal Rules — section dividers with ---, ***, and ___
• Markdown HTML — use HTML tags inside Markdown documents
• Markdown Task Lists — checkbox syntax, nested checklists, and GitHub GFM
• Markdown Footnotes — references, citations, and GitHub GFM support
• GitHub Markdown — GFM syntax, README examples, and GitHub-specific features
• GitHub Flavored Markdown (GFM) — deep dive into GFM extensions and compatibility

Coming soon

• README Guide — templates, structure, and professional README workflows
• Markdown Line Breaks — spacing rules and hard line breaks

The best way to learn GitHub Flavored Markdown is by writing it yourself. Open the Markdown Editor to experiment with GFM formatting while previewing the rendered output in real time.