Introduction

It might seem like creating web content is magic, but one tool makes it easy: markdown. What is markdown? Well, it’s a language for formatting documents using plain old text. So, if you have any computer with a plain text editor (even something like Notepad), you can write in Markdown! For live rendering, you can even use online editors like Dillinger. In this post, we’ll talk about how to write documents like blog posts in markdown. If you want to make a post on this website, you can either give me your markdown file, or post it yourself through GitHub.

Here is an outline of the topics we’ll cover. If you’re just looking for a cheatsheet, I would recommend this awesome reference.

• Formatting text
• Formatting blocks of text
  • Block quotes
  • Code blocks
• Adding some structure
  • Headings
  • Lists
  • Tables

Formatting text

In word processors (like Word or Pages), you use buttons to format text, and the text appears to you as you formatted it: bolded text is bolded, and italicized text is italicized. In markdown, however, you use text annotations for formatting. While your text won’t appear formatted in your editor, it is human-readable, and can easily be converted into a formatted document like a web page.

Style	Markdown	Output
italics	This is some *italicized* text	This is some italicized text
bold	This is some **bold** text	This is some bold text
nested bold/italics	This is some **bold _and_ italicized** text	This is some bold and italicized text
all bold/italics	This is some ***bold and italicized*** text	This is some bold and italicized text
strikethrough	This is some ~~bad~~ text	This is some bad text
code	This is some `code`	This is some code
link	This is a [link](https://google.com)	This is a link
image	This is an image: 	This is an image

That’s it! And if you need anything else (e.g., superscript), you can always use raw HTML: x<sup>2</sup> turns into x².

Formatting blocks of text

In addition to basic text formatting, you can also do formatting on blocks of text. There are two main cases here: quotes and code blocks.

Block quotes

Block quotes are sections of text that you’d like to put in its own little box. Although they are usually used for quotes, you can use them whenever. To make a block quote, just put > before each line of text!

Markdown:

1
2
3
4
> This is one, really, really, really, really,
> really, really, really, really, really,
> really, really, really, really, really,
> really long block of text.

Output:

This is one, really, really, really, really, really, really, really, really, really, really, really, really, really, really, really long block of text.

Code blocks

The other main usage for block formatting is when you have code blocks of any sort. To make a code block, just wrap the code with ``` on either side!

Markdown:

1
2
3
4
5
6
7
8
9
10
11
12
```
def fibonacci(n):
	""" Compute the nth number in the fibonacci sequence. """
	if n <= 0:
        return 0
    elif n == 1 or n == 2:
        return 1
     else:
        return fibonacci(n-1) + fibonacci(n-2)
 
print([ fibonacci(x) for x in range(10) ])
```

Output:

1
2
3
4
5
6
7
8
9
10
def fibonacci(n):
	""" Compute the nth number in the fibonacci sequence. """
	if n <= 0:
        return 0
    elif n == 1 or n == 2:
        return 1
     else:
        return fibonacci(n-1) + fibonacci(n-2)
 
print([ fibonacci(x) for x in range(10) ])

If you want to add syntax highlighting, just add the name of the programming language after the first set of ```’s!

Markdown:

1
2
3
4
5
6
7
8
9
10
11
12
```python
def fibonacci(n):
	""" Compute the nth number in the fibonacci sequence. """
	if n <= 0:
        return 0
    elif n == 1 or n == 2:
        return 1
     else:
        return fibonacci(n-1) + fibonacci(n-2)
 
print([ fibonacci(x) for x in range(10) ])
```

Output:

1
2
3
4
5
6
7
8
9
10
def fibonacci(n):
	""" Compute the nth number in the fibonacci sequence. """
	if n <= 0:
        return 0
    elif n == 1 or n == 2:
        return 1
     else:
        return fibonacci(n-1) + fibonacci(n-2)
 
print([ fibonacci(x) for x in range(10) ])

Adding some structure

Now that you have all of your text formatted, you might want to add some structure to your document. Thankfully, this is just as easy as text formatting.

Headings

Headings are (sub)titles that introduce different sections of your document, denoted by #. They come in six levels of varying size:

Markdown:

1
2
3
4
5
6
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Output:

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Lists

There are two types of lists in markdown: unordered and ordered lists.

To make an unordered list, simply use the dash - with indentation for sub-bullets:

Markdown:

1
2
3
4
- first thing
- second thing
  - oh yeah, one more thing
- third thing

Output:

• first thing
• second thing
  • oh yeah, one more thing
• third thing

To make an ordered list, you can use digits and periods instead of dashes:

Markdown:

1
2
3
4
1. first thing
2. second thing
   - oh yeah, one more thing
3. third thing

Output:

1. first thing
2. second thing
   • oh yeah, one more thing
3. third thing

Tables

Finally, you can make tables using a combination of the pipe character |, dashes -, colons :, and text. Each line of text represents one row of the table, and each cell in a row is separated by a pipe |. The first row (after an optional table header) specifies the alignment of text in the table using dashes and colons: :--- for left-, :---: for center-, and ---: for right-aligned (at least 3 dashes, you can use more for padding).

Here’s an example of a table with one right-aligned column, one center-aligned column, and one left-aligned column.

Markdown:

1
2
3
|                   Column 1 |        Column 2        | Column 3                  |
| -------------------------: | :--------------------: | :------------------------ |
| this text is right-aligned |  this text is centered | this text is left-aligned |

Output: