DOCS-MD.COMMarkdown sharing for AI-native workflows

GitHub Flavored Markdown (GFM) cheat sheet

Updated

GitHub Flavored Markdown is CommonMark plus five spec extensions — tables, task lists, strikethrough, bare-URL autolinks and an HTML tag filter — and github.com layers alerts, footnotes, math, mermaid, emoji shortcodes, @mentions and issue references on top. Each block below shows the syntax on the left and the rendered result on the right; the tables say which features are in the spec and which only work on github.com.

GFM vs CommonMark vs github.com

"GFM spec" is what any GFM-compatible renderer (remark-gfm, GitLab, cmark-gfm) must support. "github.com" is what the website renders on top of the spec.

FeatureSyntaxCommonMarkGFM specgithub.com
Tables| a | b | | --- | --- |—Yes (extension)Yes
Task lists- [ ] todo / - [x] done—Yes (extension)Yes, clickable in issues
Strikethrough~~text~~ or ~text~—Yes (1 or 2 tildes)Yes
Autolinks (bare URLs)https://… or www.…Only <https://…>Yes (extension)Yes
Disallowed raw HTML<script>, <style>, <iframe>…Passed throughFiltered (tagfilter)Filtered
Footnotestext[^1] … [^1]: note—Not in specYes (not in wikis)
Alerts> [!NOTE]—Not in specYes, 5 types
Math$x^2$, $$…$$, ```math—Not in specYes (MathJax)
Mermaid diagrams```mermaid—Not in specYes (+ geojson, topojson, stl)
Emoji shortcodes:tada:—Not in specYes
@mentions@user, @org/team—Not in specYes (notifies)
Issue / PR references#26, GH-26, owner/repo#26—Not in specYes (not in wikis or files)
Commit SHA linksa5c3785…, owner/repo@sha—Not in specYes
Collapsible sections<details><summary>Raw HTMLRaw HTMLYes, styled
Color chips`#0969DA`Inline codeInline codeIssues, PRs, discussions only
Heading anchors[Jump](#my-heading)No ids generatedNo ids generatedAuto-generated slugs
Underline<ins>text</ins>Raw HTMLRaw HTMLYes
Sub / superscript<sub>2</sub> <sup>2</sup>Raw HTMLRaw HTMLYes

Text styling

Bold, italic, strikethrough

**bold** or __bold__
*italic* or _italic_
***bold italic***
~~strikethrough~~ or ~strikethrough~

bold or bold italic or italic bold italic strikethrough or strikethrough

GFM accepts one or two tildes for strikethrough; three or more do nothing. Most other renderers need exactly two.

Strikethrough guide →

Subscript, superscript, underline (HTML)

H<sub>2</sub>O and E = mc<sup>2</sup> and <ins>underlined</ins>

No markdown syntax for these on GitHub — the docs prescribe the <sub>, <sup> and <ins> tags. This preview strips raw HTML; GitHub renders it.

Underline guide →

Color chip (issues, PRs, discussions only)

Brand blue is `#0969DA`, also `rgb(9, 105, 218)` or `hsl(212, 92%, 45%)`.

Brand blue is #0969DA, also rgb(9, 105, 218) or hsl(212, 92%, 45%).

A HEX, RGB or HSL value in backticks with no spaces inside gets a colour swatch — but only in issues, pull requests and discussions, never in .md files.

Tables

Table with alignment

| Left | Center | Right |
| :--- | :----: | ----: |
| a    |   b    |     c |
LeftCenterRight
abc

Needs a header row and a delimiter row of at least three dashes per column; colons set alignment. A literal | inside a cell must be written \|.

Build one with the table generator →

Task lists

Checkboxes

- [x] Write the code
- [ ] Write the tests
- [ ] \(Optional) Open a follow-up issue
  • Write the code
  • Write the tests
  • (Optional) Open a follow-up issue

In issues and PRs the boxes are clickable and the file updates. Escape a leading parenthesis after the box (\() or the item breaks.

Checkbox guide →

Code

Fenced block with language

```diff
- const old = 1;
+ const fresh = 2;
```
- const old = 1;
+ const fresh = 2;

The identifier after the fence picks the highlighter (Linguist). Unknown tags fall back to plain text — see the language table below.

Code block guide →

Inline code and the `#` color chip trap

Run `git status`; a value like `#0969DA` gets a colour swatch in issues.

Run git status; a value like #0969DA gets a colour swatch in issues.

Alerts

A blockquote whose first line is [!TYPE] renders as a coloured callout with an icon on github.com. Five types, uppercase, one per blockquote; they cannot be nested inside other elements.

The five alert types

> [!NOTE]
> Useful information that users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information users need to succeed.

> [!WARNING]
> Urgent info to avoid problems.

> [!CAUTION]
> Risks or negative outcomes of an action.

Note Useful information that users should know.

Tip Helpful advice for doing things better.

Important Key information users need to succeed.

Warning Urgent info to avoid problems.

Caution Risks or negative outcomes of an action.

Outside github.com (and GitLab, which copied the syntax) the text [!NOTE] is shown literally inside a plain blockquote, which is what the preview approximates.

Blockquote guide: nesting, attribution, callouts →

Footnotes

Reference and definition

GFM is a superset of CommonMark.[^1]

[^1]: Per the GFM spec, version 0.29-gfm.
  A second line needs two leading spaces.

GFM is a superset of CommonMark.1

Footnotes

  1. Per the GFM spec, version 0.29-gfm. A second line needs two leading spaces. ↩

Definitions render at the bottom of the page wherever you put them. Not supported in GitHub wikis, and not part of the GFM spec itself.

Footnotes guide →

Math (LaTeX)

Inline and block math

Inline: $\sqrt{3x-1}+(1+x)^2$ or $`\sqrt{3x-1}`$ when the expression clashes with markdown.

$$
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right)
$$

```math
\frac{a}{b}
```

Rendered with MathJax in issues, discussions, PRs, wikis and .md files. A literal dollar on the same line as math must be written <span>$</span>100; inside math use \$.

Math guide →

Mermaid and other diagrams

Mermaid flowchart

```mermaid
graph TD
  A[Push] --> B{CI green?}
  B -->|yes| C[Merge]
  B -->|no| D[Fix]
```

GitHub also renders ```geojson and ```topojson as maps and ```stl as a 3D model. Put `info` in a mermaid block to see which Mermaid version GitHub runs.

Mermaid timeline examples →

Emoji shortcodes

:shortcode:

Ship it :shipit: :+1: :tada:

Typing : opens an autocomplete on github.com. Shortcodes are a GitHub feature, not markdown — CommonMark renderers print the colons.

Emoji on the general cheat sheet →

HTML that GitHub keeps

Collapsible section

<details>

<summary>Tips for collapsed sections</summary>

Markdown **works** here after a blank line.

</details>

Add open to <details open> to start expanded. GitHub filters <script>, <style>, <iframe>, <title>, <textarea>, <xmp>, <noembed>, <noframes> and <plaintext> (the tagfilter extension).

Collapsible section guide →

Hidden comment

<!-- Reviewers: this paragraph is hidden in the rendered README -->
Visible text.

Hidden in the rendered page but present in the source — anyone who opens the raw file sees it.

Comment guide →

Line breaks and escaping

Line break in a .md file

Two trailing spaces  
or a backslash\
or <br/> end a line.

Two trailing spaces
or a backslash
or a br tag end a line.

In issues, PRs and discussions a single newline is already a line break; in .md files it is not, so you need one of the three forms.

New line guide →

Escaping

\*not italic\*, \#not-a-heading, \[not a link\]

*not italic*, #not-a-heading, [not a link]

A backslash disables the next markdown character. Escaping does not work in issue or PR titles.

Escape characters guide →

Alert types on GitHub

First line of the blockquoteUse it forRendered as
> [!NOTE]Useful information that users should know, even when skimming content.Blue, info icon
> [!TIP]Helpful advice for doing things better or more easily.Green, lightbulb icon
> [!IMPORTANT]Key information users need to know to achieve their goal.Purple, report icon
> [!WARNING]Urgent info that needs immediate user attention to avoid problems.Yellow, alert icon
> [!CAUTION]Advises about risks or negative outcomes of certain actions.Red, stop icon

Fence language tags GitHub highlights

GitHub uses Linguist to pick a highlighter; any language name or alias from its list works. The ones that show up most in READMEs:

TagAlso acceptedLanguage
```jsjavascript, nodeJavaScript
```tstypescriptTypeScript
```jsx—JSX
```tsx—TSX
```pythonpy, python3Python
```java—Java
```c—C
```cppc++C++
```csharpcs, c#C#
```gogolangGo
```rustrsRust
```rubyrbRuby
```php—PHP
```swift—Swift
```kotlinktKotlin
```bashsh, shell, zshShell
```powershellps1, pwshPowerShell
```sql—SQL
```htmlxhtmlHTML
```css—CSS
```jsonjsonc, json5JSON
```yamlymlYAML
```toml—TOML
```markdownmdMarkdown
```diffpatchDiff (adds +/− colouring)
```mermaid—Rendered as a diagram, not highlighted
```math—Rendered as LaTeX, not highlighted

What is GitHub Flavored Markdown?

GitHub Flavored Markdown (GFM) is the dialect of markdown GitHub uses for READMEs, issues, pull requests, discussions and wikis. The GFM spec (version 0.29-gfm) is a strict superset of CommonMark that adds five extensions: tables, task list items, strikethrough, extended autolinks and a filter for disallowed raw HTML. On top of the spec, github.com renders footnotes, alerts, math, mermaid, emoji shortcodes, @mentions and issue references.

What is the difference between GFM and CommonMark?

CommonMark is the base specification: headings, emphasis, lists, links, images, code, blockquotes and raw HTML. GFM adds tables, task lists, strikethrough, bare-URL autolinks and the tagfilter that neutralises <script>, <style>, <iframe> and similar tags. Everything valid in CommonMark renders identically in GFM.

Full flavor comparison →

Does GFM support footnotes?

GitHub.com renders footnotes (text[^1] with a [^1]: definition), but they are not part of the GFM spec, and they do not work in GitHub wikis. Other renderers that claim GFM support (remark-gfm, GitLab, many static site generators) usually include them, but check before relying on it.

How do I write an alert or callout in GitHub markdown?

Start a blockquote with one of [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] on its own line, then continue the quote with the message. GitHub renders a coloured box with an icon. The docs recommend one or two per article, never consecutive, and alerts cannot be nested inside lists or other elements.

Blockquote and callout guide →

Can I write LaTeX math in a GitHub README?

Yes. Inline math goes between single dollar signs ($x^2$) or $`…`$ when the expression contains markdown characters; block math goes between $$ delimiters on their own lines or in a ```math fence. GitHub uses MathJax and renders it in .md files, issues, PRs, discussions and wikis.

Which diagrams render on GitHub?

Mermaid (```mermaid), GeoJSON and TopoJSON maps (```geojson, ```topojson) and ASCII STL 3D models (```stl), in the same places as math: issues, discussions, PRs, wikis and markdown files. PlantUML, Graphviz and D2 do not render natively.

Why does my markdown look different on GitHub than in my editor?

Usually one of four things: alerts and emoji shortcodes are github.com features that editors show as literal text; GitHub inserts a line break for every newline in issues and PRs but not in .md files; GitHub strips <script>, <style> and <iframe>; and heading anchors follow GitHub's own slug rules, so a table of contents built for another tool can point at the wrong ids.

Related tools and sheets

Check a README before pushing with the GitHub README viewer, scaffold one with the README generator or README templates, add badges, lint it with markdown lint, and compare GFM with every other dialect on the markdown flavors page. The general markdown cheat sheet covers the CommonMark core.

Sources