Material to support teaching in Environmental Science at The University of Western Australia

Units ENVT3361, ENVT4461, and ENVT5503

The yaml header

The “yaml” header sets up how the markdown will “knit” to a document format such as HTML or MS Word. The default yaml header we get from making a new basic R markdown file (always between 2 lines of ‑‑‑) looks something like:

---
title: "One page of R Markdown"
author: "Andrew Rate"
date: "2025-02-21" 
output: html_document
---

We can add to, or change, these options for more control over document appearance. Some of the options can be changed by clicking on ⚙ ▼ at the top of the RStudio Source pane, then selecting Output options....

We can also type in the options manually, paying attention to the exact spacing of indents. Here's an example with explanatory comments:

---
title: "One Page of R Markdown"
subtitle: "A brief summary of useful features"        # a subtitle which will appear below the title
author: "Andrew Rate"
date: "2025-02-21" 
output:                      # line break after 'output:' if we want options for each format
  html_document:             # indent each output format by 2 spaces, followed by colon
    theme: yeti              # built in themes control fonts, colours, etc. indent options 4 spaces
    code_folding: show       # show (or hide) code chunks in output
    self_contained: no       # self_contained output doesn't need to link to any files e.g. images
    number_sections: no      # yes/no if we want to auto munber headings
    smart: no                # smart formatting: convert "" to “”, -- to an 'en dash', etc. 
    toc: true                # do we want a Table Of Contents? (true or false)
    toc_depth: 3             # how many Heading levels for table of contents?
    toc_float: true          # Should table of contents stay in place while page is scrolled?
  word_document:             # we can include options for additional formats
    toc: false
    highlight: kate          # theme for formatting code in outputted chunks
---

In General

In R Markdown text:

A blank line inserts a paragraph break
A new line is ignored and treated as a space, unless there are 2 spaces at the end of the previous line, in which case a line break is inserted
multiple spaces are counted as single spaces

Formatting text as headings

# Heading Level 1 becomes

Heading Level 1

## Heading Level 2 becomes

Heading Level 2

and so on.

Text formatting

To make text italic, we enclose it between asterisks or underscores:

∗emphasised∗ becomes emphasised

_italicised_ becomes italicised

To make text bold, we enclose it between double asterisks:

∗∗obvious∗∗ becomes obvious

To format text as inline code, we enclose it between backticks:

՝function()՝ becomes function()

Subscripts and superscripts

To make text _subscript, we enclose it in tildes ~:

H~2~O becomes H₂O

To make text ^superscript, we enclose it in carets ^:

E = mc^2^ becomes E = mc²

*h* = 6.626 × 10^-34^ becomes h = 6.626 × 10^-34

H~2~PO~4~^−^ becomes H₂PO₄⁻

Inserting links

The link text goes within [], and the URL goes within (); the URL can be followed by options within {} (note that there are no spaces in between). For example:

[click here for map](https://link.mazemap.com/x6Gi6x2Y){target="_blank"} becomes click here for map.

The phrase ‘click here for map’ becomes the hyperlink, and the URL https://link.mazemap.com/x6Gi6x2Y is opened in a new browser tab since the following text within {} is target="_blank".

Inserting images

Usually we will insert images as plots that are the output of code chunks. We can also insert images from other sources:

We use ![] to insert an image followed immediately by the image URL within (), and any image options following immediately within {}. For example, ![](https://upload.wikimedia.org/wikipedia/commons/c/c1/Rlogo.png){width="10%"}
will result in:

If we include text within the ![], this will become a caption and the alt-text for the image: ![R logo](https://upload.wikimedia.org/wikipedia/commons/c/c1/Rlogo.png){width="10%"}
will result in:

R logo

We should always include alt-text for accessibility. If we don't want the caption (or are making a caption in another way), the way to do this would be
![](https://upload.wikimedia.org/wikipedia/commons/c/c1/Rlogo.png){width="10%" alt="R logo"}

Lists

We can make bulleted lists by preceding lines of text with * or -:

* first bullet
* second bullet
* last bullet

would be formatted as

first bullet
second bullet
last bullet

We can make numbered lists by preceding lines of text with numbers with periods:

1. first list item
1. second list item  # we could make this '2. second list item' if we want
1. last list item    # we could make this '3. third list item' if we want

would be formatted as

first list item
second list item
last list item

Lists can have nested levels using 4-space indents, for example:

* level 1 bullet
    * level 2 bullet
        * level 3 bullet

level 1 bullet
- level 2 bullet
  - level 3 bullet

1. first list item
    a. sub-item a
    a. sub-item b
        i. sub-sub item i
        
1. second list item

1. last list item

first list item
1. sub-item a
2. sub-item b
  1. sub-sub item i
second list item
last list item

Notice the change in list item line spacing! (and how it doesn't work perfectly)

Additional Formatting using HTML

We don't need to know a lot of html code to enhance our R Markdown output (this works for both HTML and MS Word outputs). We can insert html code using the RStudio Visual Editor (the other tab on the source pane), but we usually still need to know the code to insert. Here are a few code snippets that I have found useful:

Font size and colour

The next sentence (not this one) is blue 9 pt font. 
<span style="font-size:10pt; color:blue;">This sentence is in blue 9pt font.</span>

The next sentence (not this one) is blue 9 pt font. This sentence is in blue 9pt font.

Font shading and typeface

The next sentence (not this one) is serif font in cyan shading. 
<span style="font-family: cambria, serif; background-color:cyan;">This sentence is serif font in cyan shading.</span>

The next sentence (not this one) is serif font in cyan shading. This sentence is serif font in cyan shading.

`<div…>` tags

Use in preference to html tables for boxed text, for better accessibility.

<div style="border: 2px solid #039; background-color:#f8e8d8; padding: 8px;">
Text  
inside  
box
</div>

Text
inside
box

Table formatting

Only use tables for tabular data or information. Rather than write html directly, it's usually better to use a specific table package, such as flextable, which we will look at later.

<table width="90%" border="1">
<tr>
<td align="center" colspan=2>**double-width cell value**</td>
<td align="left" style="background-color: #e0e0e0;">*grey-shaded* cell</td>
</tr>
<tr style="background-color: #c0c0f0;">
<td align="right">right-aligned<br>(whole row shaded blue)</td>
<td align="center">center-aligned<br>(whole row shaded blue)</td>
<td align="left">left-aligned<br>(whole row shaded blue)</td>
</tr>
</table>

double-width cell value		grey-shaded cell
right-aligned (whole row shaded blue)	center-aligned (whole row shaded blue)	left-aligned (whole row shaded blue)

Individual table cells can have custom borders, e.g.:

<td style=". . .; border-bottom: 1px solid black;">
We can specify border-top, border-bottom, border-left, & border-right.
Instead of solid, can have dotted, dashed, double, groove, ridge,...
</td>                                                             # (no output shown)

Special characters

`code`	symbol	`code`	symbol	`code`	symbol	`code`	symbol	`code`	symbol	`code`	symbol
`<`	<	`>`	>	`≤`	≤	`≥`	≥	`≈`	≈	`≠`	≠
`&equiv;`	≡	`½`	½	`¼`	¼	`¾`	¾	`⇌`	⇌	`⇨`	⇨
`α`	α	`β`	β	`γ`	γ	`θ`	θ	`μ`	μ	`π`	π
`°`	°	`±`	±	`¹`	¹	`²`	²	`³`	³	`×`	×
`∑`	∑	`∞`	∞	`&prop;`	∝	`∈`	∈	`−`	−	`÷`	÷
`–`	–	`—`	—	`•`	•	`&permil;`	‰	`&there4;`	∴	`Δ`	Δ
`‘`	‘	`’`	’	`“`	“	`”`	”	`&sime;`	≃	` `	^{non-break space}

See https://www.toptal.com/designers/htmlarrows/ for a complete list.

Miscellaneous but no less useful

This sets default font size for knitting R markdown to html documents – include directly after yaml header

<style type="text/css">
  body{
  font-size: 12pt;
}
</style>

Line breaks

Line breaks can be added with <br>, and this may be a better option than leaving a double space at the end of lines which is the ‘R Markdown’ method, since the <br> is visible on-screen. For example:

This is a sentence where<br>this section starts on a new line

results in

This is a sentence where
this section starts on a new line

Horizontal rule with defined color and thickness

<hr style="height: 5px; background-color: blue;" />

We will deal with R Markdown code chunk options in a subsequent section.

Here's a useful R Markdown Cheat Sheet.

🔚

CC-BY-SA • All content by Ratey-AtUWA. My employer does not necessarily know about or endorse the content of this website.
Created with rmarkdown in RStudio. Currently using the free yeti theme from Bootswatch.