Practical guide 6 min read
Markdown cheat sheet: the syntax, with examples
Headings, lists, links, tables, code, task lists, footnotes and alert boxes: every bit of Markdown you'll use, with an example to copy for each.
How Markdown works
Markdown is plain text with a few symbols that mean formatting: a # makes a heading, ** around words makes them bold, a - at the start of a line makes a list item. The file stays readable as it is, and any Markdown app turns it into a formatted page.
Everything below is GitHub Flavored Markdown, the version GitHub, GitLab, Reddit, Obsidian, VS Code and most other apps understand. A few extras (alert boxes, maths and diagrams) are marked as such, because not every app shows them.
To try any example, paste it into the Markdown Editor. The preview updates as you type.
Headings
Start a line with one to six # signs and a space. One # is the biggest heading, six the smallest.
# Document title
## Section
### Subsection
Use one # heading for the title, then ## for sections. Most apps link each heading, so ## Getting started can be linked to as #getting-started.
Paragraphs and line breaks
A blank line starts a new paragraph. Lines with no blank line between them join into one paragraph, which is why a list of names typed one per line can come out as a single line.
This is one paragraph,
even though it's typed on two lines.
This is a second paragraph.
End a line with a backslash\
to break the line without starting a new paragraph.
Two spaces at the end of a line also break it, but they're invisible and easy to delete by accident, so the backslash is safer.
Bold, italic and strikethrough
**bold** *italic* ***bold and italic*** ~~strikethrough~~
Underscores work too (__bold__, _italic_), but not inside a word, so snake_case_names stay as they are. To make part of a word bold, use asterisks: un**believ**able.
Lists
Start each line with -, * or + for bullets, or a number and a full stop for a numbered list. Indent a line to nest it under the one above.
- Milk
- Bread
- Wholemeal
- Sourdough
1. Preheat the oven
2. Mix the batter
3. Bake for 25 minutes
The numbers in a numbered list don't have to be right: Markdown counts for you, starting from the first number. Writing every item as 1. saves renumbering when you add a step. Nested items under a numbered item need three spaces, so they line up with the text after 1..
Task lists
Add [ ] or [x] after the bullet for a checkbox.
- [x] Book the venue
- [ ] Send the invitations
Links and images
[LabAnvil](https://www.labanvil.com)
[A link with a tooltip](https://www.labanvil.com "Shown on hover")
<https://www.labanvil.com>
An image is a link with ! in front, and the text in square brackets is its description for screen readers and for when it can't load. Web addresses on their own are usually turned into links automatically, and the angle brackets make sure they are.
When the same address appears several times, or a paragraph is getting hard to read, put the address at the end instead:
Read the [setup guide][setup] before you start.
[setup]: https://example.com/docs/setup
Code
Wrap a word or command in backticks for code inside a sentence: `npm install`. If the code itself has a backtick, wrap it in two: `` a`b ``.
For a block of code, put three backticks on the lines before and after it. Name the language after the opening backticks to colour the code.
```python
def greet(name):
return f"Hello, {name}!"
```
Lines indented by four spaces are also a code block, but fences are clearer and are the only way to name the language.
Tables
Separate the columns with | and put a line of dashes under the header row. Colons in that line set the alignment: :--- left, :---: centred and ---: right.
| Item | Qty | Price |
| :-------- | :-: | ----: |
| Coffee | 2 | $7.00 |
| Croissant | 1 | $3.50 |
The columns don't have to line up in the text, so this works just as well:
| Item | Qty | Price |
| :--- | :-: | ----: |
| Coffee | 2 | $7.00 |
To put a | inside a cell, write \|. Tables are tedious to type by hand, so the Markdown Table Generator lets you fill in a grid, or paste cells from Excel or Google Sheets, and writes the table for you.
Quotes and alert boxes
Start lines with > to quote them. Quotes can hold any other Markdown, including lists and more quotes.
> The best way to predict the future is to invent it.
>
> — Alan Kay
GitHub, and some other apps, turn a quote that starts with [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] into a coloured alert box. Apps that don't know them show an ordinary quote.
> [!WARNING]
> Back up your files before updating.
Footnotes
Put [^1] where the footnote mark should go, and the note itself anywhere in the document. The notes are gathered at the end, with links back.
Markdown was created in 2004.[^1]
[^1]: By John Gruber, with help from Aaron Swartz.
The label doesn't have to be a number: [^source] works too, and the notes are numbered in the order they're used.
Horizontal lines
Three or more dashes, asterisks or underscores on a line of their own draw a line across the page:
---
Leave a blank line above it. Directly under a line of text, --- turns that text into a heading instead, which is an old way of writing ## headings.
Maths and diagrams
GitHub, GitLab, Obsidian and the LabAnvil Markdown tools also show maths written in LaTeX, between dollar signs, and diagrams written in Mermaid.
The area of a circle is $A = \pi r^2$.
$$
\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}
$$
If a price such as $5 turns into maths in an app, write the dollar sign as \$.
```mermaid
graph LR
Draft --> Review --> Publish
```
Showing a symbol as it is
Put a backslash before a symbol to show it instead of formatting with it: \*not italic\*, \# not a heading, 1986\. A great year (without the backslash, that line would start a numbered list). It works for any of \ ` * _ { } [ ] ( ) # + - . ! |.
HTML in Markdown
Most apps also accept some HTML for things Markdown has no symbol for, such as keyboard keys and sections that open on a click:
Press <kbd>Ctrl</kbd> + <kbd>S</kbd> to save.
<details>
<summary>Show the answer</summary>
It was the butler.
</details>
Which tags work depends on the app: GitHub removes anything that could run code or change its page's style.
Checking your Markdown
The Markdown Linter points out mistakes such as skipped heading levels, missing blank lines and bare links, and fixes many of them in one go. The Markdown Formatter tidies spacing, lists and table columns so the text reads well too.
Both run in your browser, like every LabAnvil Markdown tool: what you type isn't uploaded. The page still loads website assets, and analytics may apply as explained in the privacy policy.