GitHub Flavoured Markdown

GitHub Flavoured Markdown (GFM) is GitHub's extended version of standard Markdown. It is the formatting language used across all of GitHub — in issue descriptions, pull request bodies, comments, READMEs, wikis, and anywhere else you write text on the platform. GFM includes everything from standard Markdown (headings, bold, lists, links, code blocks) and adds a set of GitHub-specific features that make collaborative communication significantly more powerful.

If you have not read the Markdown topic in this series, it covers the standard syntax that GFM builds on. This topic focuses on what GFM adds on top of it.

Where GFM Is Used

GFM renders in:

• Issue titles and descriptions
• Pull request titles and descriptions
• Comments on issues, pull requests, and commits
• Review comments and suggestions
• README files and other repository documentation
• Wikis
• GitHub Discussions

Any text box on GitHub that shows a "Write" tab and a "Preview" tab supports GFM.

Task Lists

Task lists are one of GFM's most useful features — particularly in pull requests and issues. They render as interactive checkboxes that can be ticked directly on the page without editing the underlying Markdown.

- [x] Write the implementation
- [x] Add unit tests
- [ ] Update the documentation
- [ ] Request review

The [x] syntax renders as a checked box; [ ] renders as an unchecked box. Clicking a checkbox on the rendered page updates the underlying comment automatically — no editing required.

Task lists in the issue and PR list

GitHub surfaces task list progress as metadata in the issue and PR list views. If a PR description contains a task list with four items and two are checked, the list view shows a small progress indicator — "2 of 4 tasks". This makes it easy to track progress on a PR without opening it.

Task lists are particularly useful when a PR covers multiple related changes or when you open a PR early to track implementation progress as a team.

Fenced Code Blocks with Syntax Highlighting

Standard Markdown supports inline code with backticks and fenced code blocks with triple backticks. GFM extends this by adding syntax highlighting when you specify a language identifier after the opening fence:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

GitHub renders the block with colour-coded syntax appropriate for the specified language. Supported language identifiers include javascript, typescript, python, jsx, tsx, html, css, scss, bash, json, yaml, sql, go, rust, and many others.

Always specify the language — it significantly improves readability for reviewers and makes code in comments feel like code rather than plain text.

Tables

GFM supports tables using pipes and hyphens:

| Column 1 | Column 2 | Column 3 |
| :---     | :---:    | ---:     |
| Left     | Centre   | Right    |
| aligned  | aligned  | aligned  |

Alignment is controlled by the colon position in the separator row:

• :--- — left-aligned (default)
• :---: — centre-aligned
• ---: — right-aligned

Tables are useful in PR descriptions for comparing before/after behaviour, listing options with trade-offs, or presenting structured reference information.

Strikethrough

GFM adds strikethrough using double tildes:

~~This text is struck through~~

Renders as: This text is struck through

Commonly used in issue comments to show that a previously stated plan has changed without deleting the original text — preserving the history of the conversation.

Autolinks

GFM automatically converts plain URLs into clickable links without any special syntax:

Visit https://github.com for more information.

This also applies to issue and PR references, commit hashes, and other GitHub-specific references covered below.

GitHub-Specific References

GFM handles several GitHub-specific reference types and renders them as clickable links automatically:

These references create bidirectional links — the referenced item also shows a cross-reference back to where it was mentioned.

Quoting

To quote text from another comment when replying, prefix each line with >:

> The timeout should be configurable per environment.

Agreed — added `TIMEOUT_MS` as an environment variable in the latest commit.

Renders as a visually distinct indented block. The keyboard shortcut: highlight the text you want to quote in any GitHub comment and press r — GitHub pre-fills the reply box with the quoted text.

Emoji

GitHub supports emoji shortcodes anywhere in GFM:

Great work :tada: — this is exactly what we needed :+1:

Type : in any GitHub comment box to trigger the emoji autocompleter. A searchable list of all available emoji is available at https://emojipedia.org or the GitHub emoji cheat sheet at https://github.com/ikatyang/emoji-cheat-sheet.

Emoji are widely used in GitHub comments and commit messages to add tone and context — :bug: for bug fixes, :sparkles: for new features, :memo: for documentation, :fire: for removing code.

Images and Drag-and-Drop

Images can be embedded in GFM using standard Markdown image syntax:

![Alt text](https://example.com/image.png)

GitHub also supports drag-and-drop image uploading directly into any comment or description text area. Drag an image file onto the text area and GitHub uploads it automatically, inserting the correct Markdown image syntax at the cursor position. This works for screenshots, diagrams, error messages, and before/after comparisons — all common in PR descriptions and issue reports.

Collapsible Sections

GFM supports HTML <details> and <summary> elements for collapsible sections — useful for long logs, stack traces, or supplementary information that should not dominate the comment:

<details>
<summary>Full error log (click to expand)</summary>

Error: Cannot read properties of undefined (reading 'map') at Array.map (<anonymous>) at processItems (app.js:47:23)

</details>

The <summary> text is always visible. Everything inside <details> is hidden until the reader clicks to expand. This is particularly useful in bug reports where a full stack trace or log output would otherwise make the comment very long.

Footnotes

GFM supports footnotes for adding references or supplementary notes without interrupting the flow of the main text:

This approach follows the recommendations from the RFC.[^1]

[^1]: RFC 9110 — HTTP Semantics, published June 2022.

The [^1] renders as a superscript link that jumps to the footnote definition at the bottom of the rendered content.

GFM in README Files

Everything covered in this topic applies to README files and other repository documentation. READMEs are the most visible GFM documents in a repository — they are rendered on the repository landing page and are the first thing visitors see.

A few additional considerations for READMEs:

• Relative links work in READMEs — [Contributing guide](CONTRIBUTING.md) links to another file in the same repository.
• Badges — small status images from services like shields.io — are commonly embedded in READMEs to show build status, test coverage, version numbers, and licence.

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

Summary