What is markdown?

It’s a light weight computer writing language that is super easy to learn and super portable. I.e. you can use it to write anything quickly and easily. Whether it’s just some notes like for this blog post, some shareable workshop or an entire paper.

It’s based on html so it’s very very common on blogs, forums, etc. For example, stackoverflow posts, Github, this blog, etc..

Basics

### A title

A title

The # sign is for titles, you can pile them up recursiverly (e.g. #### is sub-sub-sub-sub-section):

Something *in italic*

Something in italic

Something **bold**

Something bold

Some `code`

Some code

You can also write entire code snippets (more on that later):

\```
code snippets (without the \)
\```

Have some [links](macrofun-sheffield.github.io)

Have some links

Or insert some images:

![](http://tguillerme.github.io/images/rawgit.png)

Make a list using :

 * my list 
 * your list
 * a list

• my list
• your list
• a list

Or with numbers

 1. my list 
 2. your list
 3. a list

1. my list
2. your list
3. a list

Comments are inserted like in html using: <!-- and -->

 <!-- This is a comment -->

<!--
This
is
also
a
comment
-->

Tables are easy like this (use this generator)

| A | B | C | D | E |
|---|---|---|---|---|
| 1 | 2 | 3 | 4 | 5 |
| 6 | 7 | 8 | 9 | 0 |

You can find more specific info in the markdown guide.

Finally you can do anything more fancy in html by just inserting raw html code:

<h4>
<font size = "3"><b>Calculating functional diversity metrics using neighbor-joining trees.</b>
<p><b>Cardoso P</b>, <font color="#ff7400">Guillerme T</font>, Mammola S, Matthews TJ, Rigal F, Graco-Roza C, Stahls G, Carvalho JC. <i>Ecography</i> 2024 <a href="https://nsojournals.onlinelibrary.wiley.com/doi/10.1111/ecog.07156">doi.org/10.1111/ecog.07156</a>.</font></p>
</h4>

Rmarkdown

Okay, all that is cool but this is where it gets better: if you have a nicely configured IDE (like Rstudio for example - or I use Sublime Text, a very very nice one!) you can use it to write and evaluate (run) your code! You’ll need to install some packages first, namely "rmarkdown" and "knitr" (more at the end). You do that by specifying the language of the code snippet:

\```{r}
## Like this, but without the \
## This a comment in R by the way!
\```

## Like this, but without the \
## This a comment in R by the way!

You can use it to evaluate any kind of code:

## This is a hard one:
1 + 2

And tada! It prints and evaluates the results!

You can also do it for plotting for example:

## What does this do?
plot(1, col = "red")

You can also do some more complex things like printing tables using the knitr::kable function:

my_table <-  summary(iris)
knitr::kable(my_table)

Table 1: this is my results

You can also directly evaluate things in text using r 1+1 for example or r ncol(iris).

You can then configure a lot of things in the header of the snippet (the \``{r} bit) like whether to evaluate it ({r, eval = TRUE}), to print it ({r, echo = TRUE}), to specify the plot dimensions ({r, fig.height = 1, fig.width = 1}`), etc… Everything is neatly explained here.

Using all that you can easily get some nice anotated and runnable code like this one or even some entirely reproducible papers like this one.