GitHub Markdown — Features Specific to GitHub Flavored Markdown

GitHub Flavored Markdown (GFM) is GitHub’s extension of CommonMark. It adds features specifically useful in a code collaboration context: task lists, issue references, mentions, and code formatting.

Use the Markdown Preview to preview Markdown rendering.

Task lists

Checkboxes in list items:

- [x] Write unit tests
- [x] Fix the login bug
- [ ] Update documentation
- [ ] Deploy to staging

Renders as interactive checkboxes in GitHub issues and PRs. Checking a box updates the Markdown source.

Issue and PR references

GitHub auto-links issue and PR numbers:

Fixes #123
Closes #456
Related to #789

This PR implements the feature from issue #101.

Using fixes, closes, or resolves (case-insensitive) before an issue number will automatically close that issue when the PR is merged.

Cross-repository references:

See myorg/other-repo#456

User and team mentions

@username — notify a user
@org/team-name — notify an entire team

Mentions trigger notifications and create a link to the user/team profile.

Commit references

Full SHA:    abc1234567890abcdef
Short SHA:   abc1234
With repo:   myorg/myrepo@abc1234

GitHub auto-links commit SHAs to the commit view.

Emoji

:tada: :bug: :rocket: :white_check_mark: :x:

Renders as: 🎉 🐛 🚀 ✅ ❌

Full list at github.com/ikatyang/emoji-cheat-sheet.

Collapsed sections with <details>

<details>
<summary>Click to expand</summary>

Content here is hidden until clicked.

```javascript
// This code block is inside a collapsed section
console.log('expanded!');

Useful for long code examples, changelogs, or optional reading in READMEs.

Footnotes (GFM extension)

Here's a statement with a footnote.[^1]

Another statement.[^note]

[^1]: This is the footnote text.
[^note]: Named footnotes work too.

Renders footnotes at the bottom of the page with back-links.

Alerts / callouts (newer GFM)

GitHub added alert blocks in 2023:

> [!NOTE]
> Important information to note.

> [!TIP]
> A helpful tip.

> [!IMPORTANT]
> Critical information.

> [!WARNING]
> Potential issue to be aware of.

> [!CAUTION]
> Risky action warning.

Each renders with a distinct icon and color.

Strikethrough

~~This text is crossed out~~

This text is crossed out

Autolinks

GitHub auto-links URLs and email addresses in Markdown:

Visit https://example.com for more info.
Contact support@example.com with questions.

Both become clickable links automatically.

Tables (GFM)

Standard Markdown doesn’t include tables; GFM adds them:

| Name    | Role    |
| :------ | :------ |
| Alice   | Admin   |
| Bob     | Viewer  |

README best practices

Structure for a good GitHub README:

# Project Name

Short description of what this project does.

## Features

- Feature 1
- Feature 2

## Installation

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

## Usage

```javascript
const lib = require('your-package');
lib.doSomething();
```

## API

| Method | Parameters | Returns | Description |
| :----- | :--------- | :------ | :---------- |
| `foo(x)` | `x: string` | `string` | Does foo |

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

MIT — see [LICENSE](./LICENSE).

GitHub-specific markdown in issues and PRs

Issues and PRs also support:

• Related issues panel — using close/fix keywords
• Task lists — track progress and show a progress bar
• Labels — #label syntax doesn’t work but @mention does
• Reactions — emoji reactions on comments

Related tools

• Markdown Preview — preview Markdown rendering
• Markdown Cheatsheet — complete syntax reference
• Markdown Code Blocks — syntax highlighting