9  Markdown basics

Markdown is a simple and minimalist markup language aimed at reducing distractions caused by the continuous need to format text. Markdown enables writers to focus on writting. Jupyter notebooks can combine code with documentation written in Markdown to provide additional information without cluttering the code with comments. Markdown also enables the use of rich media such as hyperlinks, images, videos, and equations. These features make Jupyter notebooks great for creating both reproducible research articles and teaching content.

Markdown is a markup language created by John Gruber to speed up formatting without having to write HTML (HyperText markup Language, the language we use to write websites). Markdown is eventually translate into HTML code. There is no global standard, and there are slightly different variations of Markdown. The Github-flavored (Kramdown) markdown official documentation can be found here: https://github.github.com/gfm/

The list of example below is only aimed at getting you started. I encourage you to visit the following two links for detailed syntax, cheatsheets, and more comprehensive examples:

• Excellent syntax guide

• Adam Pritchard’s popular Markdown examples

• John Gruber’s original specifications

Comments

Markdown does not seem to have an official way of adding comments. However, we can fool several Markdown interpreters by preceding text with the following expression [//]:

[//]: This is a comment

Note that this trick might not work in some Markdown editors like Typora, but it does seem to work in Github.

Line breaks

Pressing the enter key will not generate empty lines. Because Markdown eventually is converted into HTML, we can use HTML tags to expand the editing and styling possibilities in our document. So, to add a line break, we can use the self-closing line break tag: <br/>.

some text
</br>
more text

Headers

Represented by adding 1 to 6 leading # signs

# Title header
## Sub-title header
### Sub-sub-title header

Sub-title header

Sub-sub-title header

Emphasis

*italic text*
_italic text_
**bold text**
__bold text__
~~striked text~~

italic text

italic text

bold text

bold text

text

Highlighting

To calculate the `sin(90)` first import the `math` module`

To calculate the sin(90) first import the math module`

Monospace font

Indent text using the Tab key to generate a monospace font.

Inline equations

$y = ax+b$

y = ax+b

Block equations

Example equation for calculating actual vapor pressure (Eq. 17, FAO-56):

$$ea = \frac{eTmin\frac{RHmax}{100}+eTmax\frac{RHmin}{100}}{2}$$ 

ea = \frac{eTmin\frac{RHmax}{100}+eTmax\frac{RHmin}{100}}{2}​

ea = actual vapor pressure (kPa)

eTmax = saturation vapor pressure at temp Tmax (kPa)

eTmin = saturation vapor pressure at temp Tmin (kPa)

RHmax = maximum relative humidity (%)

RHmin = minimum relative humidity (%)

Block quotes

Use the > character to generate block quotes.

>"The programmers of tomorrow are the wizards of the future. You're going to look like you have magic powers compared to everybody else." *- Gabe Newell*

“The programmers of tomorrow are the wizards of the future. You’re going to look like you have magic powers compared to everybody else.” - Gabe Newell

Bullet lists

Any of these two alternatives:

- item 1    * item 1
- item 2    * item 2
- item 3    * item 3

will generate something similar to this: - item 1 - item 2 - item 3

Numbered Lists

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

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

In-line links

[Github-flavored markdown(https://www.wikiwand.com/en/Home_page)

Github-flavored markdown

Referenced links

[Try a live Markdown editor in your browser][1]

Some text
Some more text

[1] https://stackedit.io "Optional title to identify your source"

Try a live Markdown editor in your browser

Figures

Figures can be inserted in Markdown following this syntax:

![alt_text](https://path_to_my_image/image.jpg "My image")

Because we many times want to deploy our Markdown in Github, then using pure HTML is the best option:

<img src="upload.wikimedia.org/wikipedia/en/8/80/Wikipedia-logo-v2.svg" alt="wikipedia_logo" width="100"/>

Horizontal lines

You can use three consecutive dashes, astericks, or underscores in this fashion:

---
***
___

For instance, typing ---, we obtain the following line:

---

Code

We can write inline or block code. Inline code:

`s = "Python inline code syntax highlighting"`

s = "Python inline code syntax highlighting"

and block code:

​```python
# Creating a matrix or 2D array
M = [[1, 4, 5],
    [-5, 8, 9]]
print(M)
​```

# Creating a matrix or 2D array
M = [[1, 4, 5],
    [-5, 8, 9]]
print(M)

Tables

Simple tables are easy to write in Markdown. However, adding more than a handful of rows and/or columns can turn out to be a pain. So, if you want to display many lines I suggest using a Markdown table generator. Some Markdown editors have shortcuts and table generators and there are websites exclusively dedicated to generate Markdown tables. Below I show a trivial example:

| Textural class  | Sand (%) | Clay (%) |
|:----------------|:--------:|:--------:|
| Silty clay loam | 10       | 35       |
| Sandy loam      | 60       | 15       |
| Clay loam       | 35       | 35       |

The leftmost column is left-aligned :---, the center column is center-aligned :---:, and the righmost column is right-aligned ---:. The | characters don’t need to be aligned in order for the Mardown interpreter to properly render the table, but it certainly helps while constructing the table by hand.

Textural class	Sand (%)	Clay (%)
Silty clay loam	10	35
Sandy loam	60	15
Clay loam	35	35