Headings (core)
Start the line with one to six # marks, then a space. More # marks mean a smaller heading.
# Title
## Section
### Subsection
The space matters. Seven # marks are not a heading.
Paragraphs and line breaks (core)
A blank line starts a new paragraph. A single new line inside a paragraph does not break the line. The text flows on.
For a line break without a new paragraph, end the line with two spaces or a backslash:
First line\
Second line
Bold, italic and strikethrough
*italic* or _italic_
**bold** or __bold__
***bold and italic***
~~strikethrough~~
Italic and bold are core. Strikethrough is GFM. Use the stars if the mark sits inside a word, because _ does not work inside a word.
Lists
- Apples
- Bananas
- Green ones
- Yellow ones
1. Wake up
2. Make tea
3. Read
- [ ] Write the draft
- [x] Send the draft
Bullets can start with -, + or *. Numbered lists use a number and a . or ). The first number sets where the list starts.
To nest a list, indent the inner list so it lines up with the text of the item above. For - Bananas, that is two spaces.
Bullets and numbers are core. Task lists, the [ ] and [x] boxes, are GFM.
Links
[PilcrowMD](https://pilcrowmd.com "Optional title")
<https://pilcrowmd.com>
https://pilcrowmd.com
The first is an inline link: text in square brackets, address in round brackets. The second is an autolink in angle brackets. Both are core.
The third is a bare address with no marks. CommonMark does not turn it into a link. GFM does, for addresses that start with http://, https:// or www..
Links to a heading
To jump to a heading in the same file, link to its anchor:
## My first section
[Go to the section](#my-first-section)
The link is a normal inline link. The anchor is made from the heading text on GitHub: lowercase letters, spaces turned into hyphens, other punctuation removed. A second heading with the same text gets -1 added. Other apps may build anchors in the same way, but it is a GitHub rule, so test it.
Images
Like a link, with a ! in front:

The text in square brackets is the description (the alt text). Image syntax is core.
Quotes (core)
Start each line with >:
> The best way to learn is to try.
Code
For a short piece of code inside a sentence, use single backticks:
Run `npm test` before you commit.
To show a backtick inside the code, wrap the code in double backticks.
For a block, use a fence of three backticks. Write the language name after the opening fence:
```python
print("Hello")
```
Fences can also be made with three tildes ~~~. The language name is optional. Apps use it to colour the code. All of this is core.
Horizontal rule (core)
Three or more -, * or _ on a line by themselves:
---
Leave a blank line above ---. Directly under a line of text, it makes that text a heading instead.
Tables (GFM)
A table needs a header row, a dashes row, and data rows:
| Fruit | Price |
|--------|-------|
| Apple | 1.20 |
Tables have more rules, such as alignment and escaping the pipe. See Markdown tables: how to write and read them.
Escaping: show a mark as text (core)
Put a backslash before a mark to show it as plain text:
\*not italic\*
Any punctuation mark can be escaped this way. Backslashes do not work inside code.
Footnotes (GitHub feature)
This claim needs a source.[^1]
[^1]: Here is the source.
Footnotes are not in CommonMark or the GFM spec. GitHub supports them. The note text appears at the bottom of the page, wherever you write it in the file. GitHub does not support footnotes in wikis.
Callouts (GitHub feature)
A callout is a quote with a label on the first line:
> [!NOTE]
> Useful information the reader should know.
The types are NOTE, TIP, IMPORTANT, WARNING and CAUTION. They are not in either spec. Use them sparingly.
Reading Markdown
In a plain text editor, all these marks stay visible. A Markdown reader turns them into a clean page.
PilcrowMD shows tables, footnotes, GitHub-style callouts and links that jump to a heading, on Android and Mac. On Mac it also shows task lists.
Common questions
Which Markdown should I learn first? The core marks: headings, bold, italic, lists, links, code and quotes. They work in every Markdown app. Add tables and task lists next, because most apps support GFM.
Why does my Markdown look different in another app? Apps follow different rules. CommonMark is the base, GFM adds to it, and some features, such as footnotes and callouts, are not in either. If a mark does not work, the app probably does not support it.
Do I have to use spaces after # and -? Yes. Write # Title and - Item. Without the space, the line stays plain text.
Also on Mac: PilcrowMD for Mac (beta)