Guide

Markdown cheat sheet

Markdown is plain text with a handful of symbols that mean something: a # makes a heading, two * make bold, a - starts a list. This sheet covers the syntax you will meet in README files, notes, documentation and the answers AI assistants write, and shows each piece as the source beside the page it becomes.

Everything here is GitHub Flavored Markdown, the dialect GitHub, most editors and most AI assistants use. The results on this page are rendered by the same engine as the MarkdownPaper reader, so they are exactly what you will see there.

6 min read14 sectionsUpdated 28 Sep 2026

syntax.md

Reference guideOne symbol. One result.

# heading

** emphasis

| table

Source→Page

Headings

A line that starts with one to six # characters is a heading. One # is the title, and each extra # goes a level deeper. Leave a space after the last #.

You write

# Project title
## A section
### A subsection

You see

Project title

A section

A subsection

Most documents need one title and two or three levels under it. Headings are also what a reader's contents list is built from, so a document with good headings is one you can find your way around.

Emphasis

Wrap words in one * for italics and two for bold. Underscores work the same way, and two ~ strike a word through.

You write

This is *italic*, this is **bold**, and this is ***both***.

Underscores work too: _italic_ and __bold__.

This plan is ~~cancelled~~ on hold.

You see

This is italic, this is bold, and this is both.

Underscores work too: italic and bold.

This plan is ~~cancelled~~ on hold.

Paragraphs and line breaks

A blank line starts a new paragraph. A single line break inside a paragraph is ignored, which lets you wrap long lines in the source without changing the page. To force a break inside a paragraph, end the line with a backslash.

You write

These two lines
become one paragraph.

A backslash at the end of a line\
breaks it without starting a new paragraph.

You see

These two lines become one paragraph.

A backslash at the end of a line
breaks it without starting a new paragraph.

Lists

Start a line with -, * or + for a bulleted list, and with a number and a full stop for a numbered one. Indent by two or more spaces to nest a list inside another.

You write

- Milk
- Bread
  - Sourdough
  - Rye
- Coffee

1. Open the file
2. Read it
3. Close it

You see

Milk
Bread
- Sourdough
- Rye
Coffee

Open the file
Read it
Close it

The numbers do not have to be right: 1. on every line still counts up, which makes reordering a list painless.

Task lists

A list item that starts with [ ] is an unticked box, and [x] is a ticked one. GitHub, many note apps and the MarkdownPaper reader let you tick them.

You write

- [x] Write the outline
- [x] Draft the introduction
- [ ] Review the numbers
- [ ] Send it

You see

Write the outline
Draft the introduction
Review the numbers
Send it

Links

Put the text in square brackets and the address straight after it in round brackets. An address on its own, starting with https://, becomes a link too.

You write

Read the [contributing guide](https://example.com/contributing).

Or paste the address: https://example.com

You see

Read the contributing guide.

Or paste the address: https://example.com

Images

An image is a link with ! in front of it. The text in the square brackets is the image's description, read aloud by screen readers and shown if the image cannot load, so describe what the picture shows.

![A chart of monthly sign-ups rising through the year](signups.png)

Code

Wrap a short piece of code in backticks to set it in a monospace face. For a longer block, put three backticks on the lines above and below it, and name the language after the opening ones to colour it.

You write

Run `npm install` before starting.

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

You see

Run npm install before starting.

function greet(name) {
  return `Hello, ${name}`;
}

Tables

Draw a table with | between columns and a row of dashes under the header. A colon in that row aligns the column: on the left, on the right, or on both sides to centre it.

You write

| Plan     | Seats | Price  |
| :------- | :---: | -----: |
| Starter  | 1     | $0     |
| Team     | 10    | $49    |
| Business | 50    | $199   |

You see

Plan	Seats	Price
Starter	1	$0
Team	10	$49
Business	50	$199

The pipes do not need to line up in the source. Lining them up only makes the source easier to read.

Blockquotes

Start a line with > to quote it. Everything in the quote can be formatted, including lists and more quotes.

You write

> The best documents are read, not just written.
>
> A **bold** claim, quoted.

You see

The best documents are read, not just written.

A bold claim, quoted.

Horizontal rules

Three hyphens on a line of their own draw a rule across the page, a pause between two parts of a document.

You write

The first part ends here.

---

The second part starts here.

You see

The first part ends here.

The second part starts here.

Footnotes

Put a caret and a label in square brackets where the note belongs, and the note itself anywhere in the document after the same label and a colon. The notes are gathered at the end and numbered for you.

You write

The study covered 1,200 people.[^sample]

[^sample]: Adults in three cities, surveyed in 2025.

You see

The study covered 1,200 people.¹

Footnotes

Adults in three cities, surveyed in 2025. ↩

Escaping a symbol

To show a symbol that would otherwise format something, put a backslash in front of it.

You write

\*This is not italic\*, and \# is not a heading.

You see

*This is not italic*, and # is not a heading.

Math and diagrams

Many Markdown tools, the MarkdownPaper reader among them, also typeset mathematics written between dollar signs and draw diagrams from Mermaid code blocks. Neither is part of basic Markdown, so check that wherever you share a document supports them.

The area of a circle is $A = \pi r^2$.

$$
e^{i\pi} + 1 = 0
$$

```mermaid
flowchart LR
  Draft --> Review --> Publish
```

Paste either into the reader to see it typeset, formula and diagram both.