GitHub Markdown: Complete GFM Guide with Examples (2026)

GitHub Markdown is the formatting language used across 630 million repositories by over 180 million developers (GitHub Octoverse, 2025). Every README, issue, pull request, and wiki page on GitHub renders through a markdown processor — but the syntax goes well beyond basic Markdown. GitHub's renderer supports tables, task lists, alerts, math equations, Mermaid diagrams, and more, making it one of the most feature-rich Markdown environments available.

There is an important distinction most guides miss: GitHub Flavored Markdown (GFM) is a formal specification (v0.29-gfm) that adds exactly five extensions to CommonMark. But GitHub's actual renderer supports far more features that are not in that spec. This guide covers both — the official GFM spec and the proprietary rendering features — so you know exactly what works, where it works, and what to expect. For a broader syntax reference beyond GitHub, see our Markdown cheat sheet.

180+ million developers use GitHub Markdown across 630 million repositories, with 121 million new repos created in 2025 alone (GitHub Octoverse, 2025). The formal GFM spec has not been updated since April 2019, yet GitHub continuously ships new rendering features beyond what the spec documents.

What Is GitHub Flavored Markdown?

GitHub Flavored Markdown (GFM) is a strict superset of CommonMark maintained by GitHub. The formal specification — version 0.29-gfm, published April 6, 2019 — defines exactly five extensions over CommonMark (GFM Spec). All valid CommonMark is valid GFM, but GFM adds features that the base spec does not cover.

The five extensions in the formal GFM spec are:

1. Tables — pipe-delimited columns with alignment control
2. Task list items — checkboxes with - [ ] and - [x]
3. Strikethrough — ~~deleted text~~ (double tildes only)
4. Extended autolinks — URLs and emails recognized without angle brackets
5. Disallowed raw HTML (tagfilter) — strips nine dangerous HTML tags

Everything else you see on GitHub — alerts, math, Mermaid diagrams, footnotes, emoji shortcodes, @mentions — is part of GitHub's proprietary renderer, not the GFM specification. This distinction matters when you write Markdown intended for other platforms, because those features may not render outside of GitHub. If you want to understand the foundational format itself, start with our guide on what is Markdown.

How Do GitHub Markdown Tables Work?

Tables in GitHub Markdown use pipe characters and hyphens to create structured data grids. This is one of the five official GFM extensions (GFM Spec, Tables Extension). The syntax is straightforward but has clear limitations that trip up new users.

| Feature        | Supported | Since     |
|:---------------|:---------:|----------:|
| Tables         | Yes       | GFM Spec  |
| Task lists     | Yes       | GFM Spec  |
| Alerts         | Yes       | Dec 2023  |

The separator row controls column alignment with colons: :--- for left-aligned, :---: for centered, ---: for right-aligned. Without colons, columns default to left alignment.

Key limitation: GitHub Markdown tables do not support merged cells, row spans, or column spans. For complex table layouts, use HTML <table> tags with colspan and rowspan attributes — GitHub allows these structural HTML elements inside Markdown. For a deep dive into table syntax including generators and formatting tricks, see our complete Markdown table guide.

How Do Task List Checkboxes Work in GitHub Markdown?

Task lists use - [ ] for unchecked items and - [x] for checked items. They are part of the formal GFM spec (GFM Spec, Task List Items) and render as visual checkboxes across GitHub — but their behavior differs depending on context.

- [x] Write the introduction
- [x] Add code examples
- [ ] Review and publish

In issues and pull requests, checkboxes are interactive — clicking one toggles its checked state and edits the underlying Markdown source. This makes task lists a lightweight project-tracking tool directly inside issues. In README files and other .md files, checkboxes render as read-only visual elements.

A quick note on history: GitHub's experimental "tasklist blocks" feature (a more advanced version with nested tracking) was retired in April 2025 and replaced by the sub-issues feature (GitHub Issues Changelog, 2025). The basic - [ ] syntax remains unchanged. For more on checkbox syntax, nesting rules, and troubleshooting, see our Markdown checkbox guide.

How Does Strikethrough Work in GitHub Markdown?

Strikethrough wraps text in double tildes — ~~deleted text~~ — and renders with a horizontal line through it. This is one of the five official GFM extensions (GFM Spec, Strikethrough).

~~This text is struck through~~

One common mistake: single tildes do not work on GitHub. Some Markdown parsers accept ~text~ for strikethrough, but GitHub requires the double-tilde ~~text~~ syntax. If your strikethrough renders as plain text with tildes, check your delimiter count. For the full syntax reference including platform compatibility, see our Markdown strikethrough guide.

What Are GitHub Markdown Alerts?

Alerts (also called admonitions) are styled callout blocks that highlight important information. They are not part of the GFM spec — alerts are a GitHub renderer feature officially launched in December 2023 (GitHub Changelog, 2023), after beta testing that started in May 2022.

The syntax places a type marker inside a blockquote:

> [!NOTE]
> Useful information that users should know.
 
> [!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.

Each alert type renders with a distinctive colored left border and icon: blue for NOTE, green for TIP, purple for IMPORTANT, yellow for WARNING, and red for CAUTION. GitHub added alert support to its mobile apps in 2024 (GitHub Mobile Changelog, 2024).

Since alerts build on blockquote syntax, understanding how standard blockquotes work helps you nest content correctly. See our Markdown blockquote guide for the underlying syntax.

How Do You Write Math Equations in GitHub Markdown?

GitHub added LaTeX math rendering on May 19, 2022, using MathJax as the rendering engine (GitHub Changelog, 2022). This feature is not part of the GFM spec — it is a GitHub renderer extension. Math support on wiki pages was added in August 2022.

Inline math uses single dollar signs, and display math uses double dollar signs:

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$ for any equation $ax^2 + bx + c = 0$.
 
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

This was one of GitHub's most requested features for over eight years before implementation. If you work with LaTeX or mathematical notation regularly, our Markdown math equations guide covers the full syntax including matrices, aligned equations, and common rendering pitfalls.

How Do Mermaid Diagrams Work in GitHub Markdown?

GitHub has rendered Mermaid diagrams natively since February 14, 2022 (GitHub Blog, 2022). Write a fenced code block with the mermaid language identifier, and GitHub passes the syntax to Mermaid.js, which generates the diagram client-side in the browser. This is not part of the GFM spec.

```mermaid
graph LR
    A[Write Markdown] --> B{Need a diagram?}
    B -->|Yes| C[Use Mermaid]
    B -->|No| D[Use plain text]
    C --> E[GitHub renders it]

Supported diagram types include flowcharts, sequence diagrams, class diagrams, state diagrams, entity-relationship diagrams, Gantt charts, pie charts, user journey maps, and Git graphs. For syntax details and examples of each diagram type, see our [Mermaid diagram guide](/blog/mermaid-diagram-guide) and [Mermaid flowchart guide](/blog/mermaid-flowchart-guide).

If you work with Mermaid diagrams locally, [MacMD Viewer](/features) renders them natively using the same Mermaid.js library — so your diagrams look identical on your desktop as they do on GitHub, without needing to push and refresh the browser.

## How Do Footnotes Work in GitHub Markdown?

GitHub added footnote support on September 30, 2021 ([GitHub Changelog, 2021](https://github.blog/changelog/2021-09-30-footnotes-now-supported-in-markdown-fields/)). Footnotes are **not part of the GFM spec** — they are a renderer extension. They render as superscript numbers that link to a footnote section at the bottom of the document.

```markdown
GitHub hosts over 630 million repositories[^1] with 180+ million developers[^2].

[^1]: GitHub Octoverse 2025 report.
[^2]: Includes both individual and organizational accounts.

Limitation: Footnotes are not supported in GitHub wiki pages. For the complete footnote syntax including multi-paragraph footnotes and common formatting issues, see our Markdown footnotes guide.

What Code Block Features Does GitHub Markdown Support?

Fenced code blocks are part of the CommonMark spec, but GitHub adds syntax highlighting on top using Linguist for language detection and TextMate grammars for the highlighting itself. Linguist v9.5.0 supports over 700 languages (github-linguist/linguist, 2026).

```python
def greet(name: str) -> str:
    return f"Hello, {name}!"
```

Beyond standard language identifiers, GitHub recognizes special identifiers that trigger non-code rendering: mermaid for diagrams, geojson and topojson for maps, and stl for 3D model previews.

Syntax highlighting is technically not part of the GFM spec — the spec defines fenced code blocks with language info strings, but rendering the highlighting is implementation-specific. For a deep dive into code block syntax including nesting, indentation rules, and inline code, see our Markdown code block guide.

What Other Features Does GitHub's Markdown Renderer Support?

Beyond the GFM spec extensions and the major features above, GitHub's renderer includes several additional capabilities that are not part of any formal specification.

Emoji Shortcodes

GitHub supports 1,500+ emoji shortcodes (GitHub Emoji API) using the :emoji_name: syntax — for example, :rocket: renders as a rocket emoji and :shipit: renders the GitHub-exclusive squirrel. Direct Unicode emoji characters (copy-paste) also render correctly.

@Mentions and #References

Typing @username in issues, PRs, and discussions triggers a notification to that user. #123 auto-links to issue or PR number 123 in the same repository. Cross-repo references work with user/repo#123 for issues and user/repo@SHA for commits. These references only work in issues, PRs, discussions, and comments — not in standalone .md files rendered on GitHub (GitHub Docs).

Collapsed Sections

GitHub allows HTML <details> and <summary> tags to create expandable sections:

<details>
<summary>Click to expand</summary>
 
This content is hidden by default.
You can write **full Markdown** inside collapsed sections.
 
</details>

A blank line between the closing </summary> tag and the Markdown content is required for the Markdown to render properly. Add the open attribute to <details open> to make a section expanded by default.

Autolinks

The GFM spec includes extended autolinks — URLs like https://example.com are automatically linked without explicit Markdown link syntax. GitHub extends this further with platform-specific autolinks: issue numbers (#123), commit SHAs (first 7+ characters), and cross-repo references. For more on link syntax in Markdown, see our links in Markdown guide.

What HTML Tags Does GitHub Markdown Allow?

GitHub Markdown allows a curated set of HTML tags while blocking dangerous ones. The GFM tagfilter extension (GFM Spec, Disallowed Raw HTML) explicitly blocks nine tags by replacing their opening < with <:

<iframe>, <noembed>, <noframes>, <plaintext>, <script>, <style>, <title>, <textarea>, <xmp>

Allowed tags include structural elements (<div>, <details>, <summary>, <hr>), text formatting (<b>, <i>, <strong>, <em>, <sub>, <sup>, <kbd>, <mark>), tables (<table>, <thead>, <tbody>, <tr>, <th>, <td>), media (<img>, <picture>, <source>), and links (<a> with href).

Stripped attributes: class and id attributes are removed. Inline style attributes are stripped with limited exceptions. Only safe URL schemes are allowed: http, https, mailto, and relative URLs — javascript: URLs are stripped entirely.

Where Does GitHub Markdown Render Differently?

GitHub Markdown does not behave identically everywhere on the platform. Understanding these differences prevents formatting surprises when your README looks different from your issue comment.

The most common gotcha is newline behavior: a single newline in a README renders as a space on the same line, but the same newline in an issue comment creates a new line. Use two spaces at the end of a line followed by a newline, or a <br> tag, to force a hard line break in .md files (GitHub Community Discussion).

GitHub Pages deserves special attention. Pages uses Jekyll with kramdown in GFM mode by default — this is a different renderer from github.com (GitHub Docs, Pages). Alerts, Mermaid diagrams, and other GitHub-specific features may not render on Pages without additional plugins or a custom GitHub Actions workflow.

What Changed in GitHub Markdown Recently?

No major new syntax extensions have been added to GitHub Markdown in 2025-2026. The GFM spec itself (v0.29-gfm) has not been updated since April 2019 — it is effectively frozen while GitHub ships rendering features outside of it. Recent changes have focused on tooling rather than new syntax.

The February 2026 Agentic Workflows technical preview is notable: it lets developers write GitHub Actions workflows in plain Markdown instead of YAML. This signals that Markdown's role on GitHub continues to expand beyond documentation into operational automation.

How Do You Preview GitHub Markdown Locally?

Writing GitHub Markdown directly in a browser is slow — you push a commit, wait for the page to reload, and hope the formatting is correct. A local preview tool eliminates this feedback loop entirely.

MacMD Viewer is a native macOS app that renders GitHub Flavored Markdown with the same features you see on GitHub: tables, task lists, strikethrough, code blocks with syntax highlighting, math equations (LaTeX), Mermaid diagrams, and alert-style blockquotes. It is a read-only viewer — it does not edit your files — so it pairs with whatever editor you already use (VS Code, Vim, Sublime Text). At $19.99 one-time with no subscription, it is purpose-built for developers who write Markdown daily and want instant local rendering.

MacMD Viewer also includes a QuickLook extension: press Space on any .md file in Finder and see fully rendered Markdown without opening any app. For developers working across multiple repositories, this means scanning READMEs and changelogs as fast as scanning image thumbnails.

Download MacMD Viewer and preview your GitHub Markdown locally before you push.