Cheatsheets:Markdown

Quick reference for smart people — part of our dev cheatsheets collection.

Markdown is plain text with a few markers that a renderer turns into HTML. This page is a syntax reference for CommonMark, the standard. GitHub Flavored Markdown (GFM) extensions are covered in the GFM extensions section.

New to Markdown? Work through the CommonMark interactive tutorial first, then come back to look things up.

The running example throughout this page is a short pancake recipe.

Basic example

A recipe: one heading, one paragraph, an unordered and an ordered list.

Markdown source:

# Pancakes

A quick pancake recipe for two.

## Ingredients

- 150 g flour
- 250 ml milk

## Steps

1. Mix the flour and milk.
2. Cook the batter in a pan.

Rendered (HTML, as a CommonMark renderer produces it):

<h1>Pancakes</h1>
<p>A quick pancake recipe for two.</p>
<h2>Ingredients</h2>
<ul>
<li>150 g flour</li>
<li>250 ml milk</li>
</ul>
<h2>Steps</h2>
<ol type="1">
<li>Mix the flour and milk.</li>
<li>Cook the batter in a pan.</li>
</ol>

Rendered in the browser (the HTML above as a browser displays it):

Pancakes

A quick pancake recipe for two.

Ingredients

• 150 g flour
• 250 ml milk

Steps

1. Mix the flour and milk.
2. Cook the batter in a pan.

Paragraphs and line breaks

• A blank line separates paragraphs.
• A single newline is a soft wrap: it becomes a space.
• A backslash at the end of a line (or two trailing spaces) forces a hard break.

Without (soft wrap)	With hard break
line one line two Rendered: line one line two	line one\ line two Rendered: line one line two

Headings

One to six # markers set the level.

Source	Level
# Pancakes	h1
## Ingredients	h2
###### Note	h6
Pancakes + === on the next line	h1 (setext)
Ingredients + --- on the next line	h2 (setext)

A space between the last marker and the text is required:

Wrong (no space)	Right
#Pancakes Rendered: the line stays a paragraph and the # is literal: #Pancakes	# Pancakes Rendered: a level-1 heading: Pancakes

Emphasis

Source	Rendered
*italic* or _italic_	italic
**bold** or __bold__	bold
***both***	both

Links and images

Inline links take the form [text](URL); images add a ! and an alt text: ![alt text](image.png).

Source	Rendered
[CommonMark](https://commonmark.org)	CommonMark
[CommonMark][cm] with [cm]: https://commonmark.org later	reference-style link

Lists

Unordered markers -, * and + are interchangeable. Ordered lists number from the first item's number, whatever you write. Nest with an indentation:

- fruit
  - apple
  - pear
- veg

Rendered:

• fruit
  • apple
  • pear
• veg

A blank line between items makes a loose list: each item is wrapped in a paragraph.

Code

Inline code — backticks; when the code itself contains a backtick, use two backticks:

Source	Rendered
`pip install markdown`	pip install markdown
`` `expr` ``	`expr`

Fenced blocks — three backticks; the word after the opening fence enables syntax highlighting:

```python
print("hi")
```

Rendered:

print("hi")

Legacy syntax: indented code blocks. Four leading spaces also produce a code block, without highlighting. This form is not recommended — it is easy to break (a blank line ends it, and the indentation must change inside lists). You may still see it in older documents; use fenced blocks instead.

Blockquotes

A line starting with > is a blockquote; >> nests. An empty > keeps paragraphs separate inside the quote.

> quoted line
>
> second quoted line

Rendered:

quoted line

second quoted line

GFM extensions

GFM (GitHub Flavored Markdown) is CommonMark plus the extensions below, used on GitHub.

Strikethrough — two tildes:

Source	Rendered
~~struck~~	struck

Tables — a header row, a separator row of dashes, then body rows. Colons in the separator row set alignment:

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

Rendered: the first column is left-, the second center- and the third right-aligned:

Left	Center	Right
a	b	c

Task lists — - [ ] and - [x] render as checkboxes:

- [x] mix the batter
- [ ] cook the pancakes

Rendered:

☑ mix the batter
☐ cook the pancakes

(The glyphs stand in for checkboxes; a GFM renderer produces clickable checkboxes.)

Escaping

A backslash makes the next character literal:

Source	Rendered
\*not italic\*	*not italic*
\# not a heading	# not a heading

Gotcha: emphasis needs word boundaries — underscores inside a word are literal, not emphasis.

Source foo_bar_baz renders as foo_bar_baz, not as "foobarbaz". Fix: use asterisks around whole words instead:

*foo bar* baz

Gotcha: Markdown inside an HTML block is not parsed — raw HTML passes through untouched.

<div>
*bold?* no, raw
</div>

renders the *bold?* literally. Fix: don't wrap Markdown in raw HTML at all:

*bold?* yes

Further reading

• CommonMark spec — the official standard
• CommonMark interactive tutorial — the recommended tutorial
• GFM spec — tables, task lists, strikethrough
• Markdown Guide — a friendly reference