4. Introduction to Markdown#

Author: Tue Nguyen

4.1. Outline#

  • What is Markdown?

  • Why use Markdown?

  • Basic Markdown syntax

  • Advanced Markdown syntax

4.2. What is Markdown?#

Markdown is a lightweight markup language that allows you to add formatting elements to plaintext such as

  • Headings

  • Bold, italic

  • Ordered/unordered lists

  • Links

  • Images

4.3. Why use Markdown?#

4.3.1. Versatility#

Markdown can be used for many purposes such as

  • Technical documentation (as this tutorial)

  • Notes and books

  • Static web pages

4.3.2. Minimal distraction#

Compared to rich-text text processors such as Microsoft Word, Markdown offers much fewer features. However, this turns out to be its main advantage. By restricting you to a small set of formatting options, Markdown forces you to

  • Focus on writing good content

  • Rather than spending time tweaking the appearances such as themes, fonts, colors, etc

4.3.3. Portability#

Unlike a Word file (.docx), a Markdown file is just a simple plain text file. Thus,

  • It can opened a many free text editors such as Notepad++, Sublime Text, Atom, or VS code

  • You won’t have to worry when migrating your files to different operating systems or cloud services because you can always access their contents

4.3.4. Easy integration#

If you plan to be a data analyst/scientist/researcher, technical documentation is part of your daily work. Markdown makes your life much easier by allowing you to mix your technical notes and executable code in the same place

4.3.5. Easy conversion#

You can easily convert a Markdown file to different formats such as PDF and HTML

4.4. Basic Markdown syntax#

4.4.1. Headings#

  • Headings are used to organize contents into sections

  • There are 6 levels from h1 to h6

    • h1: biggest

    • h6: smallest

  • There should be only one h1 heading in your whole file, which is the title of the document

  • Other sections will begin with a h2 heading

  • You should never use beyond h3 because nesting your contents too deep make it hard to follow

  • A heading starts with #, and the number of # indicates the heading level

Try the following in your notebook

# Level 1
## Level 2
### Level 3
#### Level 4
##### Level 5
###### Level 6

4.4.2. Paragraphs#

  • Two paragraphs are separated by a blank line

  • One common mistake is just using Enter and start writing the new paragraph

  • It will not work, you must add a blank line between graphs

Ex 1: wrong way to make a paragraph

Paragraph 1
Paragraph 2

Ex 2: correct way to make a paragraph

Paragraph 1

Paragraph 2

4.4.3. Lists#

A list can be an unordered, ordered, or mixed list

a) Unordered lists

  • Items in an unordered list start with a bullet point

  • To make an unordered list, place - followed by a space before each item of the list

Ex

- item 1
- item 2
- item 3

You will see something like this

  • item 1

  • item 2

  • item 3

b) Ordered list

  • To make an ordered list, place 1. followed by a space before each item of the list

  • You don’t need to manually increase the number, it will be done automatically

  • This is very convenient because you won’t have to update the numbering when inserting new items

Ex

1. item 1
1. item 2
1. item 3

You will see

  1. item 1

  2. item 2

  3. item 3

c) Nested lists

  • Lists can also be nested on multiple levels

  • However, try to keep it shallow (no more than 3 levels)

Ex 1: two-level unordered list

- item 1
    - sub-item 1.1
    - sub-item 1.2
- item 2
    - sub-item 2.1
    - sub-item 2.2

Ex 2: two-level ordered list

1. item 1
    1. sub-item 1.1
    1. sub-item 1.2
1. item 2
    1. sub-item 2.1
    1. sub-item 2.2

d) Mixed nested lists

  • For nested lists, you can mix ordered and unordered styles together

  • However, the items of the same level have the same type

Try this in your notebook

1. item 1
    - sub-item 1.1
    - sub-item 1.2
1. item 2
    - sub-item 2.1
    - sub-item 2.2

4.4.4. Emphasis#

  • **Make bold** will Make bold

  • *Make italic* will Make italic

  • ***Make bold and italic*** will Make bold and italic

4.4.5. Code fences#

  • Code fences are used to emphasize texts that should be understood as a coding element

  • Ex: variable name, an expression, or a whole code block

  • There are two types of code fences: inline and block.

a) Inline code fences

  • Inline code fences are used for short elements

  • Ex: a number, a variable name, or an expression

  • These elements stay in the line with normal texts (thus the name inline)

  • To use the inline code format, wrap your code in a pair of single backticks `

Ex

  • Numbers: `42` renders 42

  • Variable names: `profit` renders profit

  • Expressions: `y = 3*x + 1` renders y = 3*x + 1

b) Block code fences

  • Block code fences are used for a block of code, which normally spans more than one line

  • To use block style, wrap your code in a pair of triple backticks ```

  • You can specify the language to take advantage of syntax highlighting

Ex

```python
def say_hi(name):
    print(f"Hello {name}")
    print("Have a good day")
```

You will see

def say_hi(name):
    print(f"Hello {name}")
    print("Have a good day")

4.4.6. Latex#

  • Markdown supports Latex syntax so you can type math formulas easily

  • Similar to code fences, there are inline (use $) and block ($$) math formulas

a) Inline Latex Try this

The probability mass function for a binomial distribution is given by $f(x) = {n \choose x} p^{x} (1-p)^{n-x}$

You will see

The probability mass function for a binomial distribution is given by \(f(x) = {n \choose x} p^{x} (1-p)^{n-x}\)

b) Block Latex

Try this

$$
M = \begin{bmatrix}a_1 & b_1\\
a_2 & b_2 \\
a_3 & b_3
\end{bmatrix}
$$

You will see

\[\begin{split} M = \begin{bmatrix}a_1 & b_1\\ a_2 & b_2 \\ a_3 & b_3 \end{bmatrix} \end{split}\]

4.4.8. Advice#

  • The syntax introduced so far is enough for you to have a nice-looking notebook

  • I rarely use any Markdown features beyond this level.

  • Remember, the most important thing is the quality of your analysis

  • Don’t bother too much with fancy formatting

4.5. Advanced Markdown syntax#

4.5.1. Blockquotes#

  • Block quotes are used for quotes or excerpts

  • You start a blockquote with >

  • For multi-paragraph block quotes, add a blank line between paragraphs and remember to start every line with > as in the following example

Ex 1: single paragraph quotes

> My advice to you is to get married: if you find a good wife you’ll be happy; if not, you’ll become a philosopher (Socrates)

You will see

My advice to you is to get married: if you find a good wife you’ll be happy; if not, you’ll become a philosopher (Socrates)

Ex 2: multi-paragraph quotes

> My advice to you is to get married: if you find a good wife you’ll be happy; if not, you’ll become a philosopher (Socrates)
>
> Behind every great man is a woman rolling her eyes (Jim Carrey)

You will see

My advice to you is to get married: if you find a good wife you’ll be happy; if not, you’ll become a philosopher (Socrates)

Behind every great man is a woman rolling her eyes (Jim Carrey)

4.5.2. Images#

  • To insert an image, use the following syntax ![Caption](path_to_the_image)

  • You can use an absolute or a relative path

Ex

![Python logo](https://upload.wikimedia.org/wikipedia/commons/thumb/c/c3/Python-logo-notext.svg/242px-Python-logo-notext.svg.png)

You will see Python logo

4.5.3. Tables#

Try this

| id | name       | email            |
|----|------------|------------------|
| 1  | John Doe   | john@gmail.com   |
| 2  | Jane Smith | jane@hotmail.com |
| 3  | Nam Tran   | nam@yahoo.com    |

You will see

id

name

email

1

John Doe

john@gmail.com

2

Jane Smith

jane@hotmail.com

3

Nam Nguyen

nam@yahoo.com

However, my advice is not to type tables by yourself. Go to some website that offers a free Markdown table generator such as this one https://www.tablesgenerator.com/markdown_tables

4.5.4. Emails#

  • Put your email inside <> to generate a like to your email

  • When someone clicks on the link, the default email app will be launched

Ex

<pythonisfun@example.com>

You will see

mailto:pythonisfun@example.com

4.5.5. HTML#

You can also use HTML tags inside a Markdown file, and they will be parsed according to HTML rules

Ex

<div>
    <p>This is a paragraph</p>
    <p>Next one will be an unordered list</p>
    <ul>
        <li>item 1</li>
        <li><b>item 2 in bold</b></li>
        <li><span style="color: red;">item 3 in red</span></li>
    </ul>
</div>

You will see

This is a paragraph

Next one will be an unordered list

  • item 1
  • item 2 in bold
  • item 3 in red

4.6. Summary#

Headings

# Level 1
## Level 2
### Level 3
#### Level 4
##### Level 5
###### Level 6

Emphasis

Bold: **bold**
Italic: *italic*
Bold and italic: ***Bold and italic***
Strike through: ~~Strike through~~

Unordered lists

- item 1
- item 2
- item 3

Ordered lists

1. item 1
1. item 2
1. item 3

Nested lists

- item 1
    - sub-item 1.1
    - sub-item 1.2
- item 2
    - sub-item 2.1
    - sub-item 2.2

Mixed nested lists

1. item 1
    - sub-item 1.1
    - sub-item 1.2
1. item 2
    - sub-item 2.1
    - sub-item 2.2

Inline code

  • Numbers: `42`

  • Variable names: `profit`

  • Expressions: `y = 3*x + 1`

Block code

```python
def say_hi(name):
    print(f"Hello {name}")
    print("Have a good day")
```

Inline Latex

$E = mc^2$

Block Latex

$$
M = \begin{bmatrix}a_1 & b_1\\
a_2 & b_2 \\
a_3 & b_3
\end{bmatrix}
$$

Links

[Google](https://www.google.com)

Single-paragraph quotes

> This is a quote

Multi-paragraph quotes

> This is the first paragraph
>
> This is the second paragraph

Images

![Caption](path_to_the_image)

Tables

| id | name       | email            |
|----|------------|------------------|
| 1  | John Doe   | john@gmail.com   |
| 2  | Jane Smith | jane@hotmail.com |
| 3  | Nam Tran   | nam@yahoo.com    |

Emails

<pythonisfun@example.com>

HTML

<div>
    <p>This is a paragraph</p>
    <p>Next one will be an unordered list</p>
    <ul>
        <li>item 1</li>
        <li><b>item 2 in bold</b></li>
        <li><span style="color: red;">item 3 in red</span></li>
    </ul>
</div>