Markdown Cheatsheet

GitHub Flavored Markdown

Use this Markdown reference while you build software engineering projects, review code, or refresh the syntax you reach for most.

What GFM Adds

GFM is a strict superset of CommonMark, formally specified at github.github.com/gfm. Five extensions are in the spec.

Extension	Syntax	In CommonMark
Tables	Pipe tables with a delimiter row	No
Task lists	A checkbox at the start of a list item	No
Strikethrough	Double tildes around text	No
Autolinks	Bare URLs and emails become links	No
Disallowed raw HTML	A tag filter over raw HTML	Different

Everything else GitHub renders (alerts, footnotes, math, mermaid, mentions, emoji shortcodes, collapsible sections) is a GitHub site feature, not part of the GFM spec. That distinction is what breaks when a file moves to GitLab, Pandoc, or a static-site generator: the five spec extensions travel widely, the site features do not.

Task Lists

- [ ] open task
- [x] completed task
- [ ] parent task
  - [x] nested subtask
1. [ ] tasks work in ordered lists too

The space inside the empty brackets is required, and a space between the brackets and the text is required. In an issue or PR body on GitHub the checkboxes are clickable, and clicking one rewrites the Markdown source. GitHub also shows a completion count in the issue list for a body containing tasks.

Strikethrough and Autolinks

~~struck through~~
~~**struck and bold**~~
~single tilde, GitHub only, not in the GFM spec~

https://example.com          becomes a link
www.example.com              becomes a link with an implied scheme
someone@example.com          becomes a mailto link
`https://example.com`        stays literal inside a code span

Autolinking bare URLs is convenient and occasionally unwanted, and a code span is the way to opt out. GFM strips trailing punctuation such as a sentence-ending period from the link target, but a trailing closing parenthesis often still lands inside the href.

Alerts

Five callout types, rendered from a blockquote whose first line is the marker alone. GitHub-specific, not in the GFM spec.

> [!NOTE]
> Information the reader should notice even when skimming.

> [!TIP]
> Optional advice for doing something better.

> [!IMPORTANT]
> Information the reader needs in order to succeed.

> [!WARNING]
> Urgent information about a risk.

> [!CAUTION]
> A negative outcome or a dangerous action.

Only those five markers work, they must be the blockquote's first line, and alerts cannot nest. Elsewhere the marker degrades to literal bracketed text inside an ordinary quote, which is why they are safe in a README.

Collapsible Sections

There is no Markdown syntax for this, so it uses the raw HTML details element, which GitHub's sanitizer permits.

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

Markdown inside works, but the blank line above is required.

- a list
- another item

</details>

<details open>
<summary><b>Open by default</b></summary>

Content here.

</details>

The blank line after the summary tag is the part everyone forgets. Without it, the inner content is treated as raw HTML and the Markdown is not processed. Nesting details inside details works, and the open attribute expands it initially.

Mermaid, Math, and Diagrams

A fenced block tagged mermaid is rendered as a diagram on GitHub, GitLab, and Notion, and as plain code everywhere else.

Tag a fence with mermaid and GitHub renders the diagram.
Mermaid supports flowchart, sequenceDiagram, classDiagram,
stateDiagram, erDiagram, gantt, pie, and gitGraph.

Math uses LaTeX inside dollar delimiters, rendered by KaTeX. GitHub-specific.

Inline math goes between single dollar signs, as in $E = mc^2$.

Display math goes between double dollar signs on their own lines:

$$
\int_0^1 x^2 dx = \frac{1}{3}
$$

A fence tagged math also renders as display math on GitHub. Two gotchas: a literal dollar sign in prose can be misparsed as an opening delimiter, so escape it as \$, and math inside a table cell frequently fails because the pipe splitting happens first.

References, Mentions, and Emoji

Inside GitHub issues, pull requests, commit messages, and discussions, several shorthands autolink. They do not work in a repository's Markdown files.

You type	Links to
`#123`	Issue or PR 123 in this repository
`GH-123`	Same
`owner/repo#123`	Issue 123 in another repository
`@username`	That user's profile, and notifies them
`@org/team`	That team, and notifies its members
`9a3f21c`	The commit with that SHA, shown abbreviated
`owner/repo@9a3f21c`	A commit in another repository
`!123`	A pull request, GitLab only

Closing keywords in a PR description link and auto-close an issue on merge: closes #12, fixes #12, resolves #12, and their closed, fixed, resolved variants.

Emoji shortcodes are a GitHub site feature, not GFM.

:tada: :rocket: :warning: :white_check_mark: :bug:

They render nowhere else, so a Unicode emoji written directly is the portable choice.

The HTML Sanitizer

GFM's "disallowed raw HTML" extension filters a fixed list of tags, and GitHub layers a stricter allowlist on top. What you can rely on:

Allowed: details, summary, img, br, sub, sup, kbd, b, i, strong, em, code, pre, a, p, div, span, table and its parts, list elements, blockquote, h1 through h6, hr, picture, source.
Stripped: script, style, iframe, form, input, button, textarea, select, object, embed, link, meta, title, base, noscript, plaintext, xmp.
Stripped attributes: every on* event handler, style on most elements, and class and id in comment bodies.

<div align="center">
  <img src="./logo.png" width="200" alt="logo">
</div>

Press <kbd>Ctrl</kbd> + <kbd>C</kbd> to copy.

Because style and class are stripped, align attributes and img width are the only layout controls available. Anything more elaborate belongs in a real site rather than a README.