Markdown is a lightweight markup language: you write plain text with a few symbols and it turns into formatted HTML. It's what GitHub README.md files use, along with a lot of project documentation, Notion, Obsidian, Discord and Reddit.
This guide starts with a cheat sheet for quick lookups, then explains each element with an example.
Markdown cheat sheet
| Element | Syntax |
|---|---|
| Heading | # H1, ## H2, ### H3 |
| Bold | **text** |
| Italic | *text* |
| Bold and italic | ***text*** |
| Strikethrough | ~~text~~ |
| Quote | > text |
| List | - item |
| Numbered list | 1. item |
| Task list | - [ ] task |
| Link | [text](https://url.com) |
| Image |  |
| Inline code | `code` |
| Code block | ``` on a line before and after |
| Horizontal rule | --- |
How to write a heading in Markdown
Put hash symbols (#) at the start of the line. The number of hashes sets the level, from # (largest) to ###### (smallest). Leave a space between the hashes and the text.
# Level 1 heading
## Level 2 heading
### Level 3 heading
#### Level 4 heading
Use a single # per document, for the main title, and organise the rest with ## and ###.
Paragraphs and line breaks
To start a new paragraph, leave a blank line between the two blocks of text.
If you only press Enter, Markdown joins the two lines into the same paragraph. To force a line break without starting a new paragraph, end the line with two spaces or a backslash (\):
First line\
Second line, same paragraph
How to write bold and italic text in Markdown
- Bold: two asterisks (
**) or two underscores (__) on each side. - Italic: one asterisk (
*) or one underscore (_) on each side. - Bold and italic: three asterisks (
***) on each side.
**Bold** or __Bold__
*Italic* or _Italic_
***Bold and italic***
Result: Bold, Italic and Bold and italic.
To format only part of a word, use asterisks: super**important** works, while many editors ignore underscores in the middle of a word.
How to strikethrough text in Markdown
Put two tildes (~~) at the start and end of the text.
~~Strikethrough text~~
Result: Strikethrough text
How to write a quote in Markdown
Start the line with a greater-than symbol (>). For a quote inside a quote, use >>.
> This is a quote
>
>> And this is a nested quote
This is a quote
And this is a nested quote
How to make a list in Markdown
Bulleted list
Start each line with a dash (-), asterisk (*) or plus sign (+) followed by a space. Try to stick to one symbol.
- Apples
- Pears
- Oranges
- Apples
- Pears
- Oranges
Numbered list
Write a number followed by a period. The numbers don't have to be in order: Markdown numbers the list for you, so you can write 1. on every line.
1. Clone the repository
2. Install the dependencies
3. Start the project
- Clone the repository
- Install the dependencies
- Start the project
Nested lists
To put a list inside another, indent the items by two or four spaces.
- Frontend
- React
- Vue
- Backend
- Node.js
- Frontend
- React
- Vue
- Backend
- Node.js
Task list
Add [ ] for an open task and [x] for a done one. It works on GitHub, GitLab and most editors.
- [x] Write the README
- [ ] Add screenshots
- [ ] Publish the first release
- Write the README
- Add screenshots
- Publish the first release
How to add a link in Markdown
Put the link text in square brackets and the URL in parentheses, with no space between them. You can add a title in quotes that shows on hover.
[My website](https://girgetto.it)
[My website](https://girgetto.it "Home page")
<https://girgetto.it>
Result: My website
To link to a section of the same document, use the heading text in lowercase with dashes: [Go to tables](#how-to-make-a-table-in-markdown).
How to add an image in Markdown
It's the same as a link, with an exclamation mark (!) in front. The text in square brackets is the alt text: describe the image properly, because screen readers and search engines read it.
To make the image a link as well, put the image inside a link:
[](https://example.com)
Markdown can't resize an image. If you need to, use HTML: <img src="logo.png" alt="Logo" width="200">.
How to write code in Markdown
Inline code
Wrap the code in backticks (`).
Run `npm install` to install the dependencies.
Result: Run npm install to install the dependencies.
Code block
Put three backticks on a line before the code and three more after it. Add the language name right after the first three to get syntax highlighting.
```javascript
const sum = (a, b) => a + b;
console.log(sum(5, 5));
```
const sum = (a, b) => a + b;
console.log(sum(5, 5));
Some common languages: javascript, typescript, python, bash, json, html, css, diff.
How to make a table in Markdown
Separate columns with pipes (|) and put a row of dashes (---) under the header. Colons (:) in that row set each column's alignment.
| Command | Description | Required |
| :------------ | :---------------------: | -------: |
| `npm install` | Installs dependencies | Yes |
| `npm test` | Runs the tests | No |
| Command | Description | Required |
|---|---|---|
npm install |
Installs dependencies | Yes |
npm test |
Runs the tests | No |
:---aligns left:---:centres---:aligns right
The columns don't need to line up in the source: each row just needs the same number of pipes.
How to add a horizontal rule in Markdown
Write three dashes (---), asterisks (***) or underscores (___) on a line of their own. Leave a blank line before it, because --- right under a line of text turns that text into a heading.
Text above
---
Text below
How to escape characters in Markdown
To show a symbol Markdown would otherwise interpret, like an asterisk, put a backslash (\) in front of it.
\*This is not italic\*
Result: *This is not italic*
These characters can be escaped: \ ` * _ {} [] () # + - . ! |
How to make a collapsible section in Markdown
Markdown accepts HTML, so you can use the <details> and <summary> tags to create a block that opens on click. It's handy for hiding long logs or optional instructions in a README. Leave a blank line after </summary> so the Markdown inside gets processed.
<details>
<summary>Show install instructions</summary>
1. Clone the repository
2. Run `npm install`
</details>
Show install instructions
- Clone the repository
- Run
npm install
Where each feature works
The basics (headings, bold, italic, lists, links, images, quotes and code) work everywhere. Tables, strikethrough and task lists are GitHub Flavored Markdown (GFM) extensions: they work on GitHub, GitLab, VS Code and most modern editors, but some older tools don't render them.