GitHub Flavored Markdown Guide

GitHub Flavored Markdown (GFM) extends standard Markdown with features tailored for software development: task lists, tables, syntax-highlighted code blocks, alerts, autolinked references, and more. Whether you're writing a README, filing an issue, or commenting on a pull request, this guide covers every GitHub-specific Markdown feature you need to know.

What is GFM?

GitHub Flavored Markdown is GitHub's dialect of Markdown, built on top of the CommonMark specification. It adds features specifically useful in a software development context. GFM is used in:

README.md files displayed on repository pages
Issues and pull request descriptions
Comments and discussions
Wiki pages
GitHub Pages (Jekyll)
Release notes

Task Lists

Create interactive checklists in issues and pull requests. On GitHub, these render as clickable checkboxes:

- [x] Design database schema
- [x] Implement API endpoints
- [ ] Write unit tests
- [ ] Update documentation
- [ ] Deploy to staging

Task lists in issue bodies contribute to GitHub's progress indicator, showing "3 of 5 tasks complete" in issue listings. This makes them perfect for tracking sub-tasks within an issue.

Tables

GFM supports tables with alignment control using pipes and hyphens:

| Feature       | Status    | Priority |
| :------------ | :-------: | -------: |
| Authentication| Complete  | High     |
| Dashboard     | In Progress| Medium  |
| Reports       | Planned   | Low      |

Alignment is set in the separator row: :--- for left, :---: for center, ---: for right. You can use our Table Generator to build tables visually.

Alerts (Admonitions)

GitHub supports five types of alerts for highlighting important information in documentation:

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

These render as colored callout boxes on GitHub with appropriate icons. They are ideal for documentation, READMEs, and contributing guides.

Collapsible Sections

Use HTML <details> tags to create expandable/collapsible content — perfect for long logs, configuration examples, or optional information:

<details>
<summary>Click to see the full error log</summary>

```
Error: Connection refused at 127.0.0.1:5432
    at TCPConnectWrap.afterConnect [as oncomplete]
    at Protocol._enqueue
Stack trace continues...
```

</details>

You can nest Markdown inside <details> blocks — just leave a blank line after the <summary> tag.

Syntax-Highlighted Code Blocks

Specify the language after the opening triple backticks for automatic syntax highlighting:

```typescript
interface User {
  id: string;
  name: string;
  email: string;
  role: 'admin' | 'user';
}

async function getUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
}
```

GitHub supports syntax highlighting for hundreds of languages. Common identifiers include: javascript, typescript, python, ruby, go, rust, java, bash, yaml, json, sql, diff, dockerfile.

Diff Syntax Highlighting

Use the diff language to highlight additions and removals:

```diff
- const oldFunction = () => { return null; }
+ const newFunction = (param: string) => { return param; }
```

Autolinked References

GitHub automatically turns certain text patterns into clickable links:

Pattern	Links to	Example
`#123`	Issue or PR in same repo	#42
`org/repo#123`	Issue or PR in another repo	facebook/react#1234
`@username`	User profile (notifies them)	@octocat
`SHA`	Commit (first 7+ chars)	a1b2c3d
`org/repo@SHA`	Commit in another repo	org/repo@a1b2c3d
URL	Clickable hyperlink	https://github.com

Footnotes

Add footnotes to provide supplementary information without disrupting the reading flow:

This claim needs a citation.[^1]

Another statement with additional context.[^note]

[^1]: Source: Research paper, 2024.
[^note]: Extended explanation that provides
    additional context spanning multiple lines.

Mermaid Diagrams

GitHub natively renders Mermaid diagrams in Markdown files, issues, and comments:

```mermaid
graph LR
    A[Feature Branch] -->|Pull Request| B[Code Review]
    B -->|Approved| C[Merge to Main]
    C --> D[CI/CD Pipeline]
    D --> E[Deploy]
```

For a comprehensive guide to Mermaid syntax, see our Mermaid Diagrams Guide.

Math Expressions

GitHub supports LaTeX math rendering using dollar-sign delimiters:

Inline: The time complexity is $O(n \log n)$.

Block display:
$$
P(A|B) = \frac{P(B|A) \cdot P(A)}{P(B)}
$$

See our LaTeX Math Guide for a complete reference of supported commands.

README Best Practices

A great GitHub README typically includes these sections:

# Project Name

Short description of what the project does.

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

```bash
npm install your-package
```

## Quick Start

```javascript
import { thing } from 'your-package';
// Usage example
```

## Documentation

Link to full docs or describe configuration options.

## Contributing

How to contribute, link to CONTRIBUTING.md.

## License

MIT — see [LICENSE](LICENSE) for details.

Badges

Add status badges to the top of your README for quick project health overview:

![Build Status](https://img.shields.io/github/actions/workflow/status/user/repo/ci.yml)
![npm version](https://img.shields.io/npm/v/package-name)
![License](https://img.shields.io/github/license/user/repo)

Emoji

GitHub supports emoji shortcodes in all Markdown contexts:

:bug: Bug fix
:sparkles: New feature
:memo: Documentation
:rocket: Deployment
:white_check_mark: Tests passing
:warning: Breaking change

These are commonly used in commit messages and PR titles following conventional commit patterns.

Keyboard Shortcuts Display

Use the HTML <kbd> tag to display keyboard shortcuts in documentation:

Press <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> to open the command palette.

GFM vs. Standard Markdown

Feature	Standard Markdown	GFM (GitHub)
Tables	Not supported	Supported
Task lists	Not supported	Interactive checkboxes
Strikethrough	Not supported	`~~text~~`
Autolinks	URLs only	URLs, issues, users, commits
Code fencing	Indentation only	Triple backticks + language
Alerts	Not supported	5 types (NOTE, TIP, etc.)
Footnotes	Not supported	Supported
Mermaid diagrams	Not supported	Native rendering
Math (LaTeX)	Not supported	Dollar-sign delimiters

Preview your GitHub Markdown — MD Viewer supports all GFM features including alerts, Mermaid diagrams, and LaTeX math. See exactly how your README will look before pushing.

Open MD Viewer