Every Markdown rule that matters, on one page

Markdown looks like shorthand until you hit the edge cases. Two asterisks make bold text, or they do not, depending on what sits next to them. A list needs a blank line before it, or it becomes a paragraph. A backslash means something different inside a code span than outside one. Those are not quirks to memorize by feel; they are consequences of rules, and once you know the rules the edge cases stop being surprising.

This cheat sheet covers the syntax defined by CommonMark version 0.31.2, the specification that removed most of Markdown's original ambiguity, plus the four extensions GitHub Flavored Markdown adds on top. Every entry below shows the syntax you type and the HTML you get back. When a rule has a sharp edge, the edge is called out.

Key Takeaways

• CommonMark 0.31.2 defines the core language; GFM is a strict superset adding tables, task lists, strikethrough, and autolinks.
• Blank lines separate blocks. Most "why isn't my list working" problems are a missing blank line.
• Code spans and fenced blocks are literal: Markdown syntax inside them renders as plain text, not markup.
• A backslash escapes ASCII punctuation anywhere outside a code span.

What Is a Markdown Syntax Cheat Sheet?

A Markdown syntax cheat sheet is a lookup table for the symbols a parser recognizes and the HTML each one produces. It is not a style guide. It answers one question: given these characters, what will the renderer do with them?

The value is that Markdown is genuinely ambiguous without a specification. Markdown was released in 2004 by John Gruber as a deliberately loose format, and parsers disagreed about the details for roughly a decade. CommonMark fixed that by writing an unambiguous grammar backed by more than 600 conformance test cases, and it is now the baseline that GitHub, GitLab, Reddit, and most modern renderers build on. When a converter claims CommonMark support, it means it agrees with that test suite rather than approximating the original syntax.

A cheat sheet is worth keeping open because most people write Markdown for years without meeting the rules that only matter occasionally. Knowing them turns a puzzling render into a quick check.

Headings and block structure

Headings come in two forms. ATX headings use leading hashes, and CommonMark allows one to six of them, with an optional closing run:

# Level 1
###### Level 6
### Closed style ###

Setext headings underline the text instead, where a row of equals signs means level 1 and a row of hyphens means level 2:

Setext Level 1
==============

Setext Level 2
--------------

Prefer ATX. Setext level 2 is a single hyphen, and a stray hyphen under a line of text is an easy accident that silently changes a paragraph into a heading.

Level	ATX syntax	Setext syntax
1	# Heading	Heading then =====
2	## Heading	Heading then -----
3 to 6	### to ######	not available

Three more block rules carry most of the weight:

• Thematic break — three or more asterisks, hyphens, or underscores on their own line, such as ---, becomes an <hr>. Spaces between the characters are allowed, so - - - works too.
• Indented code block — four leading spaces produces a <pre><code> block. This is the older form and it is fragile, because a stray space in an otherwise normal list changes the meaning. Fenced blocks are safer.
• Fenced code block — three backticks or three tildes, optionally with a language hint after the opening fence. Tildes are the escape hatch when your code itself contains backticks.

Emphasis, and why it trips people up

Asterisks and underscores both mark emphasis, and both work in pairs:

*italic* and _italic_
**bold** and __bold__
***bold italic***

The rule people miss is that the delimiter run has to match. CommonMark counts characters in the delimiter run, and the opening and closing runs must be equal length. This is wrong and renders literally:

**bold*  and  *italic**

The fix is to pick one delimiter per pair:

**bold**  and  *italic*

A related edge case is a delimiter that opens but never closes. *unclosed renders as literal text, because an unmatched delimiter is not emphasis. This is deliberate, and it is what lets you write 2 * 3 * 4 without the asterisks turning into italics.

Lists, and the blank line people forget

Unordered lists accept three markers interchangeably, and ordered lists take numbers followed by a period:

- dash
* asterisk
+ plus

1. first
2. second

To nest, indent by the width of the parent item's content, commonly two or four spaces:

- top level
  - nested item

The single most common Markdown bug is a missing blank line before a list. Without it, the dash is read as the start of a setext heading underline or stays inside the paragraph as literal text:

This paragraph is immediately followed by a list:
- this item stays part of the paragraph

This one works:

- this item becomes a list

Ordered lists only need an increasing sequence in CommonMark; the numbers you type are not required to be sequential. But write them in order anyway, because some renderers and older parsers are stricter.

Links, images, and reference definitions

Inline links put the target in parentheses right after the label. Titles go in quotes inside those parentheses:

[link text](https://example.com)
[link with title](https://example.com "Hover title")
[escaped paren](https://example.com/a\(b\))

Images use the same shape with a leading exclamation mark, and the text in brackets is the alt attribute:

![alt text](image.png)
![alt text](image.png "Title")

Reference definitions separate the target from the label, which keeps paragraphs readable when you reuse the same URL many times. The definition goes anywhere in the document, and the label is referenced in brackets:

[commonmark]: https://spec.commonmark.org/0.31.2/

Read the [CommonMark spec][commonmark] before writing a parser.

Autolinks wrap the URL in angle brackets and need no label text, which is the cleanest way to show a bare URL without it becoming a link in every renderer:

<https://spec.commonmark.org/>

Code, and why it is literal everywhere

Inline code uses single backticks; fenced blocks use three. The defining property is that both treat their contents as literal text. This is what makes them safe:

Use `*asterisks*` to show emphasis syntax literally.

If your inline code itself needs a backtick, wrap the span in double backticks with a space on each side: `like this`.

The language hint after the opening fence is a convention rather than a CommonMark requirement, but it drives syntax highlighting in most renderers, so it is worth writing. CommonMark itself does not color code; it only guarantees the text comes through unescaped and unparsed.

Tables, task lists, and other GFM extensions

Tables are the first GFM extension and the reason a lot of documentation moved to Markdown. A pipe-delimited header row, a delimiter row of dashes, then body rows:

| Syntax | Produces |
| --- | --- |
| `**bold**` | strong emphasis |
| `*italic*` | emphasis |

Cells do not wrap across source lines in every implementation, so keep them on one line. Alignment is set with colons in the delimiter row: :--- left, :---: center, ---: right.

Task lists are the second. They are ordinary list items with a bracket at the start, and the bracket must be a literal [ ] or [x] with a following space:

- [x] shipped
- [ ] pending

Strikethrough is the third, and takes two tildes rather than one or three: ~~deleted text~~ becomes <del>. The fourth is extended autolinks, which turn bare www.example.com and bare email addresses into links without bracket syntax.

Raw HTML passthrough is the fifth thing GFM documents, and it works in the opposite direction: a block of literal HTML in your Markdown passes through untouched. That is a genuine security consideration, which is the subject of why output needs sanitizing.

Line breaks, escapes, and entities

A single newline inside a paragraph is a soft break and stays a newline. To force a <br>, either end the line with two spaces or use a backslash, which is the more visible choice:

Line one  
Line two

Line one\
Line two

A backslash escapes any ASCII punctuation character, which is how you write a literal asterisk without it becoming emphasis:

\*not emphasis\*
2 \* 3 \* 4

Inside a code span, backslashes are literal. A backslash escape does not work there, and there is no need for one, because the code span is already inert.

Named and numeric entity references pass through as well, in decimal and hexadecimal form:

  & ©
# Ӓ "

Related tools and further reading

Now that you can read the syntax, these ToolSura tools cover the work that follows it. The Markdown to HTML converter renders what you write on the left into sanitized HTML on the right, entirely in your browser. The Markdown Linter checks source for the structural problems this sheet describes, such as inconsistent heading levels and missing alt text.

If you are weighing the formats themselves rather than the syntax, Markdown vs HTML covers when each one fits. For the security question that follows any conversion, sanitizing Markdown output against XSS explains why a parser that accepts raw HTML needs a sanitizer downstream.

The authoritative references are worth bookmarking: the CommonMark specification with its full conformance suite, the GitHub Flavored Markdown spec, and the GitHub writing documentation for how the extensions behave on the platform most people meet them.