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, plus GFM (GitHub Flavored Markdown) for tables and task lists.

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>

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 Renders as: line one line two	line one\ line two Renders as: line one line two

Headings

One to six # markers set the level; a space after the last marker is required.

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

Emphasis

Source	Rendered
*italic* or _italic_	italic
**bold** or __bold__	bold
***both***	both
~~struck~~ (GFM)	struck

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
	an <img> with alt text "alt text"
[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 (HTML):

<ul>
<li>fruit
<ul>
<li>apple</li>
<li>pear</li>
</ul></li>
<li>veg</li>
</ul>

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

Task lists (GFM) — - [ ] and - [x]:

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

Renders as checkboxes:

<ul class="task-list">
<li><input type="checkbox" checked="" />mix the batter</li>
<li><input type="checkbox" />cook the pancakes</li>
</ul>

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")
```

Indented blocks — 4 leading spaces is also a code block, without highlighting:

    print("hi")

Blockquotes

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

> quoted line
>
> second quoted line

Renders as:

quoted line

second quoted line

Tables

A header row, a separator row of dashes, then body rows. Colons in the separator row set alignment (GFM):

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

Renders as a table with the first column left-, the second center- and the third right-aligned.

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

Gotcha: indented code needs 4 spaces; inside a list item, add the item's indent on top. 4 spaces inside a list item continue the paragraph instead of making code:

- item
    not code

renders "item not code" as one item. Fix: 6 spaces (4 + the list indent):

- item

      code

renders a proper code block inside the item.

Further reading

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