Overview over the most common and basic markdown commands and their syntax. Intended as a quick reference and showcase (cheatsheet).
Click to show TOC
markdown
# Headline level 1
## Sub headline (level 2)
### Sub headline (level 3)
#### Sub headline (level 4)
##### Sub headline (level 5)
###### Sub headline (level 6)
result
To create paragraphs, use a blank line to separate one or more lines of text. Unless the paragraph is in a list, don’t indent paragraphs with spaces or tabs.
markdown
I really like using Markdown.
I think I'll use it to format all of my documents from now on.
result
I really like using Markdown.
I think I'll use it to format all of my documents from now on.
To emphasize text use:
- italic: use
*italic*
OR_italic_
- bold: use
**bold**
OR__bold__
- bold and italic: use
***bold and italic***
OR___bold and italic___
- to nest one inside the other: use
*nest one **inside** the other*
OR_nest one __inside__ the other_
strikethrough: use~~strikethrough~~
Because different markdown interpreters handle underscores different it's best practice to avoid using underscores ( _ ). Use asterisks ( * ) instead when writing markdown!
In markdown any special characters are escaped by a leading backslash ( e.g. \special-char ).
character | escaped | description |
---|---|---|
\ | \\ |
backslash |
` | ` | backtick (escaping backticks in code) |
> | \> |
greater than |
* | \* |
asterisk |
_ | \_ |
underscore |
{ } | \{\} |
curly braces |
[ ] | \[\] |
square brackets |
( ) | \(\) |
parentheses |
# | \# |
hash mark |
+ | \+ |
plus sign |
- | \- |
minus sign (hyphen) |
. | \. |
dot |
! | \! |
exclamation mark |
To create a horizontal rule, use three or more asterisks ( *** ), dashes ( --- ), or underscores ( ___ ) on a line by themselves. The rendered output of all three looks identical.
markdown
***
---
_________________
result
markdown
[Link text](http://some.url.com "Link title")
[Link text](#link-id "Link title")
[Link text<a name="#link-id">](#link-id "Link title")
result
You can link to headings with custom IDs in the file by creating a standard link with a number sign (#) followed by the custom heading ID.
[Heading IDs](#heading-ids)
Other websites can link to the heading by adding the custom heading ID to the full URL of the webpage (e.g, Heading IDs).
Just enclose the "link part" of an image link with another pair of square brackets
[![image-alt-text](./images/code-tag.png "Link to CODE section")](#code)
To include an image from the local file system just put a "!" (exclamation mark) in front of a decent markdown text link.
![alternate image text](./relative/path/to/file.type "Image title")
Output
Alternatively just use "old school" HTML syntax, where you can also set any required image dimensions:
<img src="./images/markdown.png" width="75">
Output
![image-alt-text](http://url.to.image "Image title")
[![image-alt-text](http://url.to.image "Image title")](#link-URL)
- ...
Using VS Code plugin Markdown All in One
- navigate to the place in your markdown file where you want to have your TOC created and set your cursor there
- press Shift + Command + P to open the VSCode command prompt
- type >Create Table of Contents => DONE
- TOC is automatically updated on file save by default
-
Markdown All in One (Visual Studio Marketplace)
-
Markdown + Math (Visual Studio Marketplace)
-
markdownlint (Visual Studio Marketplace)
markdown
| left | center | right |
| :--- | :----: | ----: |
| 1 | 2 | 3 |
| 4 | 5 | 6 |
| 7 | 8 | 9 |
- If you have the Markdown All in One plugin installed you can format a table like so:
- First mark the table, then press 'Shift + Command + F' to format the table
result
left | center | right |
---|---|---|
1 | 2 | 3 |
4 | 5 | 6 |
7 | 8 | 9 |
Lists are a way to structure data. They allow us to group sets of related items. Lists can be "nested" (you can have lists inside lists).
Unordered lists are lists whose elements are not related to each other (nor numerically neither alphanumerically). List items of unordered lists are marked as bullets (small black circles) by default.
To start an unordered list simply start a new line using one of the following three indicating characters: asterisk ( * ), minus ( - ) or plus ( + ) character. Those indicators can be mixed.
markdown
* an asterisk ( \* ) starts an unordered list
+ alternatively use the ( \+ ) character for an unordered list
- the minus character ( \- ) can also be used for an unordered list
result
- an asterisk ( * ) starts an unordered list
- alternatively use the ( + ) character for an unordered list
- the minus character ( - ) can also be used for an unordered list
Unordered lists can be nested. The indicating characters can also be mixed when nested.
markdown
* Level 1, Item 1 using an asterisk ( \* )
* Level 2, Item 1 using an asterisk ( \* )
* Level 3, Item 1 using an asterisk ( \* )
+ Level 3, Item 2 using the ( \+ ) character
- Level 3, Item 3 using the ( \- ) character
+ Level 2, Item 2 using the ( \+ ) character
- Level 2, Item 3 using the ( \- ) character
+ Level 1, Item 2 using the ( \+ ) character
- Level 1, Item 3 using the ( \- ) character
result
-
Level 1, Item 1 using an asterisk ( * )
-
Level 2, Item 1 using an asterisk ( * )
- Level 3, Item 1 using an asterisk ( * )
- Level 3, Item 2 using the ( + ) character
- Level 3, Item 3 using the ( - ) character
- Level 2, Item 2 using the ( + ) character
- Level 2, Item 3 using the ( - ) character
-
- Level 1, Item 2 using the ( + ) character
- Level 1, Item 3 using the ( - ) character
To start an ordered list, write this:
markdown
1. this starts a list *with* numbers
+ this will show as number "2"
* this will show as number "3."
9. any number, +, -, or * will keep the list going.
* just indent by 4 spaces (or tab) to make a sub-list
1. keep indenting for more sub lists
* here i'm back to the second level
result
- this starts a list with numbers
- this will show as number "2"
- this will show as number "3."
- any number, +, -, or * will keep the list going.
- just indent by 4 spaces (or tab) to make a sub-list
- just keep indenting for more sub lists
- here i'm back to the second level
- just indent by 4 spaces (or tab) to make a sub-list
To start a check list, write this:
markdown
- [ ] this is not checked
- [ ] this is not checked too
- [x] but THIS is checked
result
- this is not checked
- this is not checked too
- but THIS is checked
markdown
1. Level 1, Item 1
2. Level 1, Item 2
3. Level 1, Item 3
result
- Level 1, Item 1
- Level 1, Item 2
- Level 1, Item 3
Start every new list item on a new line with indicator symbol "1." to auto increment the numbering.
markdown
1. Level 1, Item 1
1. Level 1, Item 2
1. Level 1, Item 3
result
- Level 1, Item 1
- Level 1, Item 2
- Level 1, Item 3
Nested list with auto counted list items.
markdown
1. Level 1, Item 1
1. Level 2, Item 1
func emptyFunc() { }
***
1. Level 2, Item 2
1. Level 2, Item 3
1. Level 1, Item 2
1. Level 2, Item 1
1. Level 3, Item 1
1. Level 3, Item 2
1. Level 3, Item 3
1. Level 2, Item 2
1. Level 2, Item 3
1. Level 1, Item 3
result
-
Level 1, Item 1
-
Level 2, Item 1
func emptyFunc() { }
-
Level 2, Item 2
-
Level 2, Item 3
-
-
Level 1, Item 2
-
Level 2, Item 1
- Level 3, Item 1
- Level 3, Item 2
- Level 3, Item 3
-
Level 2, Item 2
-
Level 2, Item 3
-
-
Level 1, Item 3
markdown
- paragraph:
- with:
linebreak (1 line space between)
- and here:
without linebreak
result
-
paragraph:
-
with:
linebreak (1 line space between)
-
and here: without linebreak
-
...
markdown
First Term
: This is the definition of the first term.
Second Term
: This is one definition of the second term.
: This is another definition of the second term.
result
First Term : This is the definition of the first term.
Second Term : This is one definition of the second term. : This is another definition of the second term.
To create a blockquote, add a " > " (greater than) in front of a paragraph.
markdown
> Dorothy followed her through many of the beautiful rooms in her castle.
result
Dorothy followed her through many of the beautiful rooms in her castle.
markdown
> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
result
Dorothy followed her through many of the beautiful rooms in her castle.
The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
Blockquotes can be nested. Add a >> in front of the paragraph you want to nest.
markdown
> Dorothy followed her through many of the beautiful rooms in her castle.
>
>> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
result
Dorothy followed her through many of the beautiful rooms in her castle.
The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
markdown
`a single line of code`
result
a single line of code
To create code blocks, there are several ways.
Indent every line of the block by at least four spaces or one tab.
markup
....{
......"firstName": "John",
......"lastName": "Smith",
......"age": 25
....}
result
{
"firstName": "John",
"lastName": "Smith",
"age": 25
}
To form code blocks in Markdown, the code can be enclosed between certain special characters. This is why these code blocks are called "fenced code blocks".
To enclose the code you want to display use three backticks (```) followed by a linebreak at the beginning and the end of your code.
markdown
```
{
"firstName": "John",
"lastName": "Smith",
"age": 25
}
```
result
{
"firstName": "John",
"lastName": "Smith",
"age": 25
}
To enclose the code you want to display use three tilde characters (~~~) followed by a linebreak at the beginning and the end of your code.
markdown
~~~
{
"firstName": "John",
"lastName": "Smith",
"age": 25
}
~~~
result
{
"firstName": "John",
"lastName": "Smith",
"age": 25
}
Many markdown processors support syntax highlighting for fenced code blocks. This feature allows you to add color highlighting for whatever language your code was written in. To add syntax highlighting, specify a language next to the backticks or tildes before the fenced code block.
JSON code
markdown
```json
{
"firstName": "John",
"lastName": "Smith",
"age": 25
}
```
result
{
"firstName": "John",
"lastName": "Smith",
"age": 25
}
HTML code
markdown
```html
<ul>
<li>
<a href="#">My code</a>
</li>
</ul>
```
result
<ul>
<li>
<a href="#">My code</a>
</li>
</ul>
JavaScript code
markdown
```js
const Complex = require('Complex');
console.log(new Complex(3, 4).abs()); // 5
```
result
const Complex = require('Complex');
console.log(new Complex(3, 4).abs()); // 5
Python code
markdown
```py
#!/usr/bin/python
import abc
```
result
#!/usr/bin/bash
import abc
Script code with leading shebang (here: bash script)
markdown
```bash
#!/usr/bin/bash
# maintain bash profiles that work on BOTH, Linux and MacOS
[[ -f ~/.bashrc ]] && . ~/.bashrc
```
result
#!/usr/bin/bash
# maintain bash profiles that work on BOTH, Linux and MacOS
[[ -f ~/.bashrc ]] && . ~/.bashrc
For more complete info, please see:
- Markdown Guide
- John Gruber's original markdown spec
- GitHub Flavoured Markdown Spec
- Basic writing and formatting syntax in GitHub
- Online Markdown editor "Dillinger"
Published under the MIT Licence