Markdown cheat sheet: the syntax you'll actually use

Markdown is a way of formatting plain text with a handful of symbols. You write **bold** and it shows as bold. It was designed to be readable even before it's formatted, which is why it's used by GitHub, Obsidian, Notion, Slack, Reddit, most documentation tools and AI assistants.

This page covers the syntax you'll use day to day.

Headings

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

Put a space after the #. Use one # heading for the title and ## for sections; skipping levels works, but a tidy outline is easier to navigate.

Emphasis

*italic* or _italic_
**bold**
~~strikethrough~~

Strikethrough is an extension: it works on GitHub, Obsidian and most modern apps, but not in every Markdown tool.

Paragraphs and line breaks

Separate paragraphs with a blank line. A single line break inside a paragraph is often ignored when the text is shown, so lines run together. If you need a hard break without a new paragraph, end the line with two spaces or use <br> where HTML is allowed.

Lists

- Apples
- Oranges
  - Blood oranges

1. First
2. Second
3. Third

Indent nested items by two or four spaces. For numbered lists, many apps renumber automatically, so 1. on every line works too.

Task lists, supported on GitHub and in many note apps:

- [ ] To do
- [x] Done

Links and images

[Docuflat](https://docuflat.com)
![Alt text describing the image](image.png)

Always write useful alt text for images: it's read aloud by screen readers and shown if the image doesn't load.

Quotes

> This is a quote.
> It can span several lines.

Code

Inline code uses single backticks: `npm install`.

Code blocks use three backticks, optionally with the language for colour highlighting:

```python
print("hello")

## Tables

- The second row (dashes) is required; it separates the header from the body.
- A colon sets alignment: `:---` left, `---:` right, `:---:` centred.
- Columns don't need to line up in the source; it just reads better if they do.
- To put a `|` inside a cell, write `\|`.

Tables are an extension too, but almost every current Markdown app supports them.

## Horizontal rule

Leave a blank line above it, otherwise some apps read the line before it as a heading.

## Escaping

To show a symbol literally, put a backslash before it: `\*not italic\*`, `\# not a heading`.

## The rules that trip people up

1. **No blank line before a list or table**, and it may not be recognised.
2. **Tabs versus spaces** in nested lists can behave differently between apps. Spaces are safer.
3. **Underscores inside words** (`file_name_v2`) are usually fine, but wrap code-like text in backticks to be sure.
4. **Different "flavours".** GitHub Flavored Markdown, CommonMark and app-specific versions agree on the basics above but differ on extras like footnotes, highlights and callouts.

## Getting existing documents into Markdown

You don't have to retype anything. Drop a PDF, Word file, spreadsheet, CSV or image on the [Docuflat converter](/) and copy the Markdown. Word files keep their headings, lists and tables; spreadsheets become tables. See [Convert Word documents to Markdown](/guides/word-to-markdown) and [How to convert a PDF to Markdown](/guides/pdf-to-markdown-converter).