Markdown cheat sheet: every common syntax, with examples

Markdown was created in 2004 by John Gruber, with help from Aaron Swartz, as a way to write formatted text that is still easy to read in its raw form. A Markdown file is just plain text, so it opens anywhere, survives copy and paste, and never gets locked inside one program. That is why it is now used everywhere from GitHub and Reddit to note apps and documentation sites.

Different apps support slightly different "flavors" of Markdown. Everything below works in the most widely used variants, including CommonMark and GitHub Flavored Markdown. Where a feature is an extension rather than core Markdown, it is marked.

Headings

Start a line with one to six hash signs, followed by a space. One hash is the largest heading; six is the smallest.

# Heading 1
## Heading 2
### Heading 3

Use a single top-level heading for the title of a note and second-level headings for its sections. Skipping levels (going from # straight to ####) works, but it makes the structure harder to follow, especially for screen readers.

Paragraphs and line breaks

Separate paragraphs with a blank line. A single line break inside a paragraph is usually ignored and joined into one line. To force a line break without starting a new paragraph, end the line with two spaces or a backslash.

This is the first paragraph.

This is the second paragraph.

Emphasis: bold, italic and strikethrough

Asterisks are the safer choice. Underscores inside words (like file_name_here) are ignored by most parsers, which prevents accidental italics in technical text, but asterisks work consistently in all positions.

Lists

For a bulleted list, start each line with a dash, asterisk or plus sign and a space. For a numbered list, use a number followed by a period.

- Milk
- Eggs
  - Free-range
- Bread

1. Preheat the oven
2. Mix the ingredients
3. Bake for 25 minutes

Indent by two to four spaces to nest a list inside another. In numbered lists, the actual numbers you type often do not matter: many renderers number items automatically, so writing 1. on every line still produces 1, 2, 3. Starting the list at a different number, such as 5., makes it begin there.

Task lists (extension)

GitHub Flavored Markdown and many note apps support checkboxes:

- [x] Book flights
- [ ] Reserve hotel
- [ ] Renew passport

An x inside the brackets marks the task as done. Support varies, so if checkboxes matter, a dedicated task list note is more reliable.

Links

Put the link text in square brackets and the address in parentheses right after it:

[Notepad Free](https://notepadfree.com)
[Notepad Free](https://notepadfree.com "Optional title")

Many renderers also turn a bare address wrapped in angle brackets, like <https://example.com>, into a clickable link. For long documents, reference-style links keep paragraphs readable:

Read the [style guide][guide] before writing.

[guide]: https://example.com/style-guide

Images

Images use the link syntax with an exclamation mark in front. The text in brackets is the alt text — a description for people who cannot see the image, and what shows if the image fails to load.

![A cat sleeping on a keyboard](https://example.com/cat.jpg)

Always write meaningful alt text. "Image" or "photo" helps nobody; "Bar chart showing sales doubling from 2024 to 2026" does.

Blockquotes

Start a line with a greater-than sign to quote text. Quotes can contain other Markdown, including lists and headings.

> The best way to get started is to quit talking and begin doing.
>
> — commonly attributed to Walt Disney

Code

Wrap short code inside a sentence with single backticks (the ` key, usually under Esc). For longer blocks, put three backticks on the line before and after. Adding a language name after the opening backticks enables syntax highlighting in many apps.

Run `npm install` first.

```js
function greet(name) {
  return 'Hello, ' + name;
}
```

Text inside code is shown exactly as typed, so it is also the easiest way to display Markdown characters without them being interpreted.

Horizontal rule

Three or more dashes, asterisks or underscores on a line by themselves draw a divider. Leave a blank line above dashes, otherwise some parsers treat the text above as a heading.

Section one

---

Section two

Tables (extension)

Tables use pipes to separate columns and a row of dashes under the header. Colons in the dash row control alignment.

| Plan  | Price | Notes          |
|:------|------:|:--------------:|
| Free  |    $0 | No sign-up     |
| Team  |   $12 | Per user/month |

The columns do not need to line up perfectly in the raw text; the renderer handles that. For anything bigger than a few rows, a spreadsheet is easier to edit.

Escaping special characters

If you want a literal asterisk, hash or underscore instead of formatting, put a backslash before it: \*not italic\*. This is handy for prices, file names and math such as 2\*3.

Common pitfalls

• Missing space after the hash. #Heading is often shown as plain text; write # Heading.
• No blank line before a list. Some renderers will not start a list directly under a paragraph. Add an empty line first.
• Inconsistent indentation. Mixing tabs and spaces in nested lists produces unpredictable results. Pick spaces and stick with them.
• Expecting every feature everywhere. Tables, task lists, strikethrough and footnotes are extensions. Check your app supports them before relying on them.

Why bother learning Markdown?

Once the basics are in your fingers, formatting becomes faster than reaching for the mouse. Your notes stay portable — a Markdown file written today will open in any text editor decades from now — and the same skill transfers to GitHub, documentation tools, chat apps and static site generators. Ten minutes with this cheat sheet is enough to cover almost everything you will need day to day.