Writing Markdown on GitHub feels simple — until you discover that task lists are interactive in Issues but static in READMEs, or that > [!NOTE] renders a beautiful callout in a README but produces plain text in a Wiki. GitHub Flavored Markdown (GFM) has quirks, and knowing them saves real frustration.

This is a complete reference for Markdown across GitHub’s different surfaces. It covers what features are available where, along with concrete patterns for making the most of each.

Table of Contents

What is GitHub Flavored Markdown?

GitHub Flavored Markdown (GFM) is GitHub’s extension of the CommonMark specification. It adds features that aren’t part of standard Markdown:

  • Tables — pipe-delimited, with alignment control
  • Task lists — - [x] done, interactive in issues
  • Strikethrough — ~~text~~
  • Autolinks — bare URLs become clickable
  • Fenced code blocks with language identifiers
  • @mentions and issue cross-references
  • Alerts (callout boxes) — added in 2023
  • Mermaid diagrams — rendered natively since 2022
  • Math expressions — using $...$ and $$...$$
  • Footnotes — [^1]: reference text

GFM is supported almost everywhere on GitHub, but some features behave differently depending on where you write them.

Features by Surface

Feature README Issues / PRs Comments Wiki
Tables ✅ ✅ ✅ ✅
Task lists (rendered) ✅ ✅ interactive ✅ ✅
Strikethrough ✅ ✅ ✅ ✅
@mentions ✅ ✅ ✅ ❌
Issue refs (#123) ✅ ✅ ✅ ❌
Alerts (> [!NOTE]) ✅ ✅ ✅ ⚠️
Mermaid diagrams ✅ ✅ ⚠️ ✅
Math ($...$) ✅ ✅ ✅ ✅
Footnotes ✅ ✅ ✅ ✅
Emoji shortcodes ✅ ✅ ✅ ✅
HTML <details> ✅ ✅ ⚠️ ✅
Collapsible <summary> ✅ ✅ ⚠️ ✅

⚠️ = partially supported or context-dependent

README Best Practices

The README is the homepage of your repository. Visitors make snap judgments based on it — a well-structured README earns more stars, contributors, and trust.

The essential structure

# Project Name

One-sentence description of what this does and who it's for.

## Installation

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

## Usage

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

## Contributing

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

## License

MIT

Badges

Badges communicate project health at a glance. They go between the description and the first heading:

![CI](https://github.com/owner/repo/actions/workflows/ci.yml/badge.svg)
![npm version](https://img.shields.io/npm/v/your-package)
![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
![Downloads](https://img.shields.io/npm/dm/your-package)

Shields.io has generators for hundreds of badge types.

Table of contents

GitHub doesn’t auto-generate a TOC, but you can create one using anchor links. GitHub auto-generates heading anchors: spaces become hyphens, everything is lowercased, punctuation is removed.

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
  - [Basic usage](#basic-usage)
  - [Advanced options](#advanced-options)
- [API Reference](#api-reference)
- [Contributing](#contributing)

For more about anchor links, see our guide to Markdown internal links.

Collapsible sections

Use HTML <details> and <summary> for content you want collapsed by default. This is great for long changelogs, large code examples, or optional configuration:

<details>
<summary>Advanced configuration options</summary>

Put your expanded content here. Note the blank line after `<summary>` —
it's required for Markdown to render inside the block.

```json
{
  "option": "value"
}
```

</details>

Centering images

GFM doesn’t support CSS classes, but you can center images with an HTML wrapper:

<p align="center">
  <img src="./docs/logo.png" width="200" alt="Project logo">
</p>

For more image options, see our Markdown image alignment guide.

Issues and Pull Requests

Issues and PRs share the same Markdown renderer as READMEs, but they add some interactive features.

Interactive task lists

Task lists in Issues and PRs are interactive — users can check boxes directly without editing the source:

## Release checklist

- [x] Write unit tests
- [x] Update changelog
- [ ] Update documentation
- [ ] Tag the release
- [ ] Publish to npm

GitHub shows completion status in the issue list (e.g., 3 of 5 tasks). For more, see our Markdown task lists guide.

GitHub auto-links many types of references in issues and PRs:

Reference Links to
#123 Issue or PR in the same repo
owner/repo#123 Issue or PR in another repo
@username GitHub user profile
@org/team GitHub team
abc1234 (7+ char SHA) Specific commit
gh-123 Shorthand for issue/PR

Close keywords: Using closes #123, fixes #123, or resolves #123 in a PR description automatically closes the referenced issue when the PR is merged into the default branch.

Issue and PR templates

Templates live in .github/ISSUE_TEMPLATE/ (for issues) or .github/pull_request_template.md (for PRs). They’re standard Markdown files with optional YAML frontmatter:

---
name: Bug report
about: Report something that isn't working
labels: bug
assignees: ''
---

## What happened?

<!-- Describe the bug clearly and concisely -->

## Steps to reproduce

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

## Expected behavior

<!-- What did you expect to happen? -->

## Environment

- OS: [e.g. macOS 14]
- Version: [e.g. 2.1.0]

HTML comments (<!-- -->) show in the template but are hidden in the rendered output, making them perfect for writing instructions to issue reporters.

GitHub Wikis

GitHub Wikis use GFM but with notable differences from READMEs:

  • No @mentions or #issue auto-links — @username and #123 are plain text
  • Separate git repository — clone at https://github.com/owner/repo.wiki.git
  • Custom sidebar — create _Sidebar.md for navigation
  • Custom footer — create _Footer.md for a footer on every page
  • File-based navigation — wiki pages link using the page title, spaces replaced with hyphens

Wiki sidebar

Create _Sidebar.md for a persistent navigation panel:

## Documentation

- [[Home]]
- [[Installation]]
- [[Configuration]]
  - [[Basic Setup]]
  - [[Advanced Options]]
- [[API Reference]]
- [[Troubleshooting]]

Wiki page links use double brackets: [[Page Name]] becomes a link to the Page-Name wiki page.

Alerts and Callouts

GitHub added native alert support in 2023. These render as styled callout boxes with colored borders and icons:

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

Alerts work in READMEs, Issues, and PRs. Support in Wikis is inconsistent — test before relying on them there. For a deep dive on callout syntax across platforms, see our Markdown admonitions guide.

Diagrams with Mermaid

GitHub renders Mermaid diagrams natively using fenced code blocks with the mermaid language identifier:

```mermaid
graph LR
    A[User] -->|HTTP request| B[Load Balancer]
    B --> C[App Server 1]
    B --> D[App Server 2]
    C --> E[(Database)]
    D --> E
```

Mermaid supports:

  • Flowcharts (graph LR, graph TD)
  • Sequence diagrams (sequenceDiagram)
  • Gantt charts (gantt)
  • Class diagrams (classDiagram)
  • Entity relationship diagrams (erDiagram)
  • State diagrams (stateDiagram-v2)

For more on embedding diagrams, see our Markdown diagrams guide.

GitHub Pages and Jekyll

GitHub Pages uses Jekyll to build sites from your repository. Jekyll adds YAML frontmatter and Liquid templating on top of Markdown.

YAML frontmatter

Frontmatter goes at the very top of the file, between --- delimiters:

---
title: My Page Title
layout: post
date: 2026-05-08
author: Jane Smith
categories: [tutorials, markdown]
---

Content starts here.

For a full reference on frontmatter options, see our YAML frontmatter guide.

Jekyll vs plain GitHub Markdown

The critical difference with Jekyll: it runs a Liquid template preprocessor over your files before Markdown rendering. This means:

  • Content between curly braces may be interpreted as template expressions
  • Code blocks that show templating syntax (Liquid, Jinja, Handlebars, etc.) need special escaping
  • Wrap problematic code blocks with the raw and endraw Liquid tags to pass content through unprocessed

This is a common stumbling block when documenting frameworks that use template syntax. Our Markdown collapsible sections guide has more on <details> patterns that also work in Jekyll sites.

Quick Reference

A few tools that pair well with GitHub Markdown:

Related reading: