GitHub Markdown: The Complete GFM Guide

GitHub uses GitHub Flavored Markdown (GFM) everywhere: README files, issues, pull requests, comments, wikis, and discussions. GFM extends standard markdown with tables, task lists, strikethrough, and auto-linking. GitHub also adds features on top of GFM that are specific to the platform.

This guide covers the full scope of what works on GitHub, from basic syntax to GitHub-only features like alerts, Mermaid diagrams, and math expressions.

Standard GFM on GitHub

These features work everywhere on GitHub and on most other platforms that support GFM:

Text Formatting

**bold** and *italic*
***bold italic***
~~strikethrough~~
`inline code`

Headings

# H1 — Use for document title
## H2 — Major sections
### H3 — Subsections

GitHub auto-generates heading IDs for anchor links. Hover over a heading to see the link icon.

Links and Images

[Link text](https://example.com)
![Alt text](/images/screenshot.png)

Relative links work in repos: [Docs](./docs/README.md) resolves to the file in the same repository.

Lists

- Bullet item
  - Nested item

1. Numbered item
2. Another item

Task Lists

- [x] Completed
- [ ] Pending

In issues and PRs, checkboxes are interactive. In README files and comments, they display but are not clickable.

Tables

| Feature | Status |
|---------|--------|
| Auth    | Done   |
| API     | WIP    |

Code Blocks

```python
def hello():
    print("Hello, world")
```

GitHub supports syntax highlighting for 200+ languages. Common identifiers: javascript, typescript, python, bash, json, go, rust, yaml, sql, html, css.

Blockquotes

> Important context for the reader.

Footnotes

Claim that needs backing[^1].

[^1]: Source: https://example.com

GitHub-Only Features

These features work on GitHub but not on most other platforms.

Alerts (Admonitions)

Styled callout boxes added in 2023:

> [!NOTE]
> Useful information for context.

> [!TIP]
> Advice to help users succeed.

> [!IMPORTANT]
> Information users should know.

> [!WARNING]
> Something that needs attention.

> [!CAUTION]
> Risk of negative outcomes.

Each type renders with a distinct color and icon. On other platforms, these appear as plain blockquotes with the [!TYPE] text visible.

Mermaid Diagrams

GitHub renders Mermaid code blocks as SVG diagrams:

```mermaid
graph TD
    A[Write Markdown] --> B[Push to GitHub]
    B --> C[README Renders]
```

Supported diagram types: flowcharts, sequence diagrams, Gantt charts, pie charts, entity-relationship diagrams, state diagrams, and more.

Math Expressions

GitHub supports LaTeX math using dollar signs:

Inline math:

The equation $E = mc^2$ describes energy-mass equivalence.

Block math:

$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \ldots + x_n
$$

Auto-Linked References

GitHub auto-links several reference types:

Relative Links

Links resolve relative to the file’s location in the repo:

See [the API docs](./docs/api.md)
See [the root README](../README.md)

This works in README files, wikis, and any rendered markdown on GitHub.

Image Theming

You can show different images for light and dark mode using HTML and the prefers-color-scheme media query:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="logo-dark.png">
  <img alt="Logo" src="logo-light.png">
</picture>

Collapsed Sections

Use the HTML <details> tag:

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

Hidden content here. Note the blank line after the summary tag.

- Works with lists
- And other markdown

</details>

GitHub renders this as a toggle section. The summary text is always visible; the rest is hidden until clicked.

Writing README Files

A README is the first thing visitors see on a GitHub repo. Here is a structure that works:

# Project Name

One-line description of what this project does.

## Installation

How to install or set up the project.

## Usage

How to use it, with code examples.

## Configuration

Available options and how to set them.

## Contributing

How others can contribute.

## License

What license the project uses.

For more, see How to Write a README.

README Badges

Badges are common in README files. They use image links from services like shields.io:

![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)

These render as small status icons showing build state, version, license, and other metadata.

Writing Issues and Pull Requests

Issue Templates

GitHub supports issue templates in .github/ISSUE_TEMPLATE/. Use markdown to define the structure:

---
name: Bug Report
about: Report a bug
---

## Description

What happened?

## Steps to Reproduce

1. Go to ...
2. Click on ...
3. See error

## Expected Behavior

What should have happened?

## Environment

- OS:
- Browser:
- Version:

PR Description Best Practices

## What

Brief description of the change.

## Why

Motivation and context.

## How

Implementation approach.

## Testing

- [ ] Unit tests pass
- [ ] Manual testing done
- [ ] No regressions found

## Screenshots

If applicable, add screenshots here.

GitHub vs Other Platforms

FAQ

What markdown format does GitHub use?

GitHub uses GitHub Flavored Markdown (GFM), which extends CommonMark with tables, task lists, strikethrough, auto-linking, and footnotes. GitHub also adds platform-specific features like alerts, Mermaid, and math expressions.

How do I preview markdown before pushing to GitHub?

Use Ctrl+Shift+V in VS Code for a local preview. You can also use the MDtoLink editor for real-time rendering. GitHub itself shows a “Preview” tab when editing files in the browser.

Can I use HTML in GitHub markdown?

Yes, with restrictions. GitHub allows common tags like <details>, <summary>, <img>, <sub>, <sup>, <kbd>, and <br>. It strips potentially dangerous tags like <script>, <style>, <iframe>, and inline event handlers.

How do I create a table of contents on GitHub?

GitHub auto-generates a TOC icon on README files with multiple headings. Click the hamburger menu icon at the top-left of the rendered content. For an explicit TOC, create a list of anchor links manually.

Try It Out

Write GitHub-style markdown with live preview in the MDtoLink editor. When your document is ready, publish it to a shareable URL, or push it to GitHub.

For the full syntax reference, see the markdown cheat sheet. For an explanation of GFM, see What Is GitHub Flavored Markdown?.