Front Matter (YAML)

Every Markdown document begins with a section of plain text written in YAML (“YAML Ain’t Markup Language”). This block of human readable code is used to define some of the document’s metadata such as the title, author, and date. It is also used to specify the document’s format (eg, HTML or pdf) and its layout (eg, theme, font).

The front matter is defined in a block of text that begins and ends with 3 dashes ---. For example, here is the YAML for a simple HTML document:

---
title: "I really like R Markdown"
author: "Mark Scheuerell"
date: "3 April 2020"
output: html_document
---

The YAML can include a lot more information as well, including fields for various pre-defined themes, a table of contents, adding citations and formatting references, and whether to use other files as formatting templates. For example, here is the YAML for this document:

---
title: "Introduction to R Markdown"
author: "Mark Scheuerell"
date: "3 April 2020"
output:
  html_document:
    theme: journal
    highlight: textmate
    toc: true
    toc_float: true
    toc_depth: 3
---

Body

The body of a Markdown document can contain a mix of variously formatted text, equations, and code. The code can be written so that it is executed upon “knitting” the document with the output displayed in the document or hidden from view. The code can also be flagged so that it is only shown for example purposes and not actually executed.

Headings

You can specify different levels of headings using the hash tag (pound) symbol #. By adding more # signs you can decrease the heading level. So, for example, the following

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

will render to

Heading 1

Heading 2

Heading 3

Heading 4

Emphasis

This is *italic*, but then so is _this_.

This is **bold**, but then so is __this__.

This is ***bold and italic***.

Oops, this is ~~a mistake~~.

This bit is <u>underlined</u>.

Block quotes

You can specify a block quote by preceding it with the > symbol, such that

> I have a dream that one day this nation will rise up and live out the true meaning of its creed: 'We hold these truths to be self-evident, that all men are created equal.'

yields

I have a dream that one day this nation will rise up and live out the true meaning of its creed: ‘We hold these truths to be self-evident, that all men are created equal.’

Lists

You can include ordered (numbered) lists, unordered (bulleted) lists, or a combination of the two in Markdown documents as well. Numbered lists simply use a number and period (1.) followed by a space and the text. For example, this text

1. This is item 1  
2. Item 2 comes next

will render to

1. This is item 1
   
2. Item 2 comes next

It also turns out that you don’t even have to use consecutive numbers to make it work. For example,

1. This is item 1  
7. Item 2 comes next

will render to

1. This is item 1
   
2. Item 2 comes next

You can specify unordered list with either an asterisk (*) or dash (-). For example, the following text

* This is a thing 
* Here is another
- And yet another

will render to

• This is a thing
• Here is another
• And yet another

Mixed lists simply use a mixture of the two constructs, such that

1. This is item 1
   * This is a thing
   * Here is another  
2. Item 2 comes next
   - And yet another

will render to

1. This is item 1
   • This is a thing
   • Here is another
     
2. Item 2 comes next
   • And yet another

Links

Please conduct your search from [this link](http://www.google.com).

Please conduct your search from [this link][1].

Inserting pictures

Check out the QERM Program's logo: ![](qerm_logo.png)

Check out the QERM Program's logo: ![][2]

[1]: http://www.google.com
[2]: qerm_logo.png

Blocks

The most common method for including code in your document is via code blocks, which can be numerous and separated by text, equations, images, etc. Just as with a typical R script, all of the code is executed in sequence, which means code can reference objects, use packages, etc that were defined or called in previous blocks. Code blocks are delimited at the beginning and end by three back-ticks (```). In addition, you need to add {r} after the beginning ``` so Markdown knows what language interpreter to use (in this case R). So, for example, here is a really basic code block

```{r}
a <- 1
b <- 2
a / b
```

By default, Markdown will show the code and the output when the document is rendered, such that above code block would look like

a <- 1
b <- 2
a / b

## [1] 0.5

```{r simple_arithmetic}
a <- 1
b <- 2
a / b
```

```{r simple_arithmetic, echo = FALSE}
a <- 1
b <- 2
a / b
```

```{r simple_arithmetic, eval = FALSE}
a <- 1
b <- 2
a / b
```

Inline

Sometimes it can be nice to include small snippets of hidden R code within a sentence. For example, an object is defined once at the beginning of a document and referenced later. Or, in a dynamic report we might want the reported results to reflect any changes to inputs, models, etc. To include inline R code, you wrap the call in back-ticks and preface it with r (eg, `r object`). You can also replace object with a valid R expression. For example, imagine we had two variables, x and y, that had been defined in a previous block of code, such that x = 2 and y = 3 . If we write

The sum of x and y is `r x + y`.

the rendered Markdown document will read

The sum of x and y is 5.

Figures

Another of Markdown’s strengths is its ability to render high-quality figures. This can be done by either inserting links to saved figures/images as shown above, or executing R code to do so. For example, this code

```{r xy_plot}
set.seeed(123)
n <- 100
x <- runif(nn, 0, 10)
e <- rnorm(nn)
y <- 1 + 0.5 * x + e
plot(x, y)
```

would produce the following plot

You can also add chunk options to change the figure’s size, location, etc. For example,

```{r xy_plot, fig.height = 4, fig.width = 4, fig.align = "center"}
set.seed(123)
n <- 100
x <- runif(n, 0, 10)
e <- rnorm(n)
y <- 1 + 0.5 * x + e
plot(x, y)
```

would instead yield

Inline

You can include equations inline by enabling the “inline math mode” through the use of a single dollar sign ($) at the beginning and end of the equation. For example,

The errors are normally distributed, such that $e_{i,j} \sim \text{N}(0, \sigma^2)$.

will render as

The errors are normally distributed, such that as \(e_{i,j} \sim \text{N}(0, \sigma^2)\).

Stand alone

In many cases, you may want to have your equations set apart from the text on lines by themselves. To do this in Markdown, begin and end the equation block with 2 dollar signs ($$). If you want equations on multiple lines, use \\ to indicate a line break. For example,

$$
y_{i,j} = \alpha + \beta x_{i,j} + e_{i,j} \\
e_{i,j} \sim \text{N}(0, \sigma^2)
$$

will render to

\[ y_{i,j} = \alpha + \beta x_{i,j} + e_{i,j} \\ e_{i,j} \sim \text{N}(0, \sigma^2) \]

and

$$
\mathbf{x}_t = \mathbf{B} \mathbf{x}_{t-1} + \mathbf{C} \mathbf{c}_t + \mathbf{w}_t \\
\mathbf{y}_t = \mathbf{Z} \mathbf{x}_t + \mathbf{a} + \mathbf{v}_t
$$

would give

\[ \mathbf{x}_t = \mathbf{B} \mathbf{x}_{t-1} + \mathbf{C} \mathbf{c}_t + \mathbf{w}_t \\ \mathbf{y}_t = \mathbf{Z} \mathbf{x}_t + \mathbf{a} + \mathbf{v}_t \]

You can also use some additional LaTeX options inside the equation block for additional formatting options. For example, the aligned command can be used with an ampersand & to align multiple equations, such that

\begin{aligned}
\text{Var}(p_{ex}) &= \text{Var}(o) - \text{Var}(e) + 2 ~ \text{Cov}(p_{ex}, e) \\
  &= \text{Var}(o) - \text{RMSE}_{ex}^2 + 2 ~ \text{Cov}(p_{ex}, e) \\
  &\approx 3.6 - 1^2 + 2 ~ \text{Cov}(p_{ex}, e).
\end{aligned}

yields

\[ \begin{aligned} \text{Var}(p_{ex}) &= \text{Var}(o) - \text{Var}(e) + 2 ~ \text{Cov}(p_{ex}, e) \\ &= \text{Var}(o) - \text{RMSE}_{ex}^2 + 2 ~ \text{Cov}(p_{ex}, e) \\ &\approx 3.6 - 1^2 + 2 (0.4) = 3.4 \end{aligned} \]

NOTE: If your preferred output format is pdf, there are additional LaTeX options for formatting equations.