1. What is R Markdown / Bookdown?
2. Basic demos of R Markdown and Bookdown, using RStudio Cloud
3. Tips & tricks

These slides were written in R Markdown, using the ioslides package. (More later.)

Visit https://mpaldridge.github.io/rmarkdown/ for:

• These slides (with hyperlinks, and accessible by screenreaders)
• R Markdown source for these slides
• A handout, produced from exactly the same R Markdown source that made the slides themselves

R Markdown is a system for writing mathematical/statistical documents.

• R Markdown documents can be produced in numerous formats, including accessible HTML.

Bookdown is a package for R Markdown that provides extra features useful for long documents.

• R Markdown example: A worksheet for MATH1710
• Bookdown example: MATH1710 lecture notes

Markdown is a “mark-up” language (like LaTeX or HTML), where special characters and commands tell the computer what formatting you want.

• Markdown is extremely easy for humans to read

Markdown is a “mark-up” language (like LaTeX or HTML), where special characters and commands tell the computer what formatting you want.

• Markdown is extremely easy for humans to read
• Programs like Pandoc can compile Markdown documents to many different formats:
  • most important: HTML (fully accessible) and PDF
  • also: EPUB ebook, Microsoft Word document, etc.
  • Can be built to multiple formats simultaneously
• Markdown is simpler than LaTeX…
  • …but much less powerful that LaTeX

R Markdown is a system to write and compile (“knit”) Markdown documents using R…

R is a programming language that is very good at doing statistics.

• R is used by most statistics academics
• We teach R to our students (in MATH1710, MATH1712, etc.)

Using the program RStudio is a convenient way to work with the language R (and with R Markdown documents).

Demos later…

R Markdown is a system to write and compile (“knit”) Markdown documents using R.

R Markdown adds to plain-Markdown:

• Mathematical equations using LaTeX notation
  • When “knitted” to HTML, this displays as fully accessible MathJax
  • Includes standard amsmath extras: mathbb, mathcal, align, align*, cases, pmatrix, etc
  • May not do super-complicated stuff
• You can include R code (or other programming languages) in cool ways
  • More on this later…

Bookdown is an extra package for R Markdown that is particularly useful for long documents.

• In HTML format, produces a full website of interlinked pages, one page per chapter
• Other HTML features: contents bar, search, colour schemes, font size adjustment, etc
• Adds LaTeX-like theorem/definition/proof environments

Compare earlier demos:

• R Markdown: A worksheet for MATH1710
• Bookdown: MATH1710 lecture notes

I strongly recommend using R Markdown via RStudio.

• (Recall that RStudio is the program to interact with the statistical programming language R)

To install on your own computer:

• First install R…
• …then install RStudio

For a first try, I recommend instead the RStudio Cloud: https://rstudio.cloud

• Browser-based RStudio – like Google Docs or Overleaf for RStudio.
• 25 hours per month free – probably won’t work for long-term use

[demo via RStudio Cloud]

# Chapter

## Section

### Subsection

Bookdown is trickier in RStudio Cloud, so I will revert to RStudio as installed on my computer.

In R Studio:

• File
• New Project
• New Directory
• Book project using bookdown
• Create Project

demo

LaTeX:

\begin{theorem}[Fermat's last theorem] \label{FLT}
No three positive integers $a$, $b$, and $c$ satisfy the equation
$a^n + b^n = c^n$ for any integer value of $n$ greater than $2$.
\end{theorem}

As we saw in Theorem \ref{FLT}\dots

R Markdown, with the Bookdown package:

::: {.theorem #FLT name="Fermat's last theorem"}
No three positive integers $a$, $b$, and $c$ satisfy the equation
$a^n + b^n = c^n$ for any integer value of $n$ greater than $2$.
:::

As we saw in Theorem \@ref(thm:FLT)...

Previously,

```{theorem}
Your theorem here.
```

had been recommended, but the newer

::: {.theorem}
Your theorem here.
:::

method is better.

Theorem-like environments in Bookdown are much less flexible than their LaTeX equivalents.

• You have theorem, lemma, corollary, proposition, conjecture, definition, example, exercise, hypothesis
  • But, unlike LaTeX, you can’t define your own new environments

Here is some R code:

data <- rnorm(100)
mean(data)
hist(data)

R experts will know that this:

• Generates 100 normally distributed random variates
• Calculates the mean of this data
• Plots a histogram of this data

I can include that R code it in an R Markdown document like this:

Here is some R code:

```{r}
data <- rnorm(100)
mean(data)
hist(data)
```

Note that the code is preceded with three “backticks” ``` and {r}, then ends with three more backticks.

The result is the following…

Note that the document displayed both the R commands and the output those commands produced.

• You can set it just to show the code…
  • …or just the output
• There are many other options here
  • See Section 2.6 of R Markdown: The Definitive Guide for details

It is apparently possible to use other programming languages in R Markdown in the same way I demonstrated R code.

• Open with, for example: ```{python}

See Chapter 15 of the R Markdown cookbook for details.

I don’t know anyone local who’s tried this out and can advise us – audience?

Tables in (R) Markdown are a bit fiddly…

| "Plain" R Markdown         | RMarkdown with Bookdown    |
|:--------------------------:|:--------------------------:|
| Good for short documents   | Good for long documents    |
| Slightly simpler to write  | Slightly trickier to write |
| PDF or accessible HTML     | PDF or accessible HTML     |
| LaTeX equations            | LaTeX equations            |
| Single HTML page           | Multi-page website         |
| No theorem environments    | Theorem environments       |

… so I recommend this online Markdown table generator.

If you use TikZ to draw pictures in LaTeX, you can do this in R Markdown too.

```{tikz demo-tikz, echo=FALSE, fig.cap="Caption", fig.alt="Alt text"}
\begin{tikzpicture}
\draw[thick] (0,0) rectangle (6,4);
\end{tikzpicture}
```

Default picture types:

• PDF pictures in PDF documents
• PNG pictures in HTML documents
  • Should be possible to produce SVG pictures – has anyone tried?

Many of us will want to knit Bookdown documents to both PDF and HTML.

• LaTeX styling for PDF output can go in preamble.tex
  • You probably have your own favourite LaTeX tweaks
• CSS styling for HTML output can go in style.css
  • I like to draw boxes around theorems, to make it clearer where the start/end
  • I like to indent new paragraphs like LaTeX does
  • I don’t want embedded videos to fill the whole page width
  • Feel free to copy my style.css file that does these (and some other things)

ClavertonDown is a package by the University of Bath, based on Bookdown.

It is arguably the gold standard in making accessible mathematical documents.

• Knits simultaneously to 7 (seven!) different formats
• High contrast colour scheme
• Technologically a bit ramshackle
• Has anyone local tried this?

Phil will (I think) demonstrate this shortly.

R Markdown has a few formats for making slides.

• The simplest – and least powerful/flexible – is ioslides (it seems to me) which is what these slides use
• R Markdown source for these slides
• In RStudio: File — New File — R Markdown and choose “Presentation”
• This is the first time I’ve done slides in R Markdown – do any of the audience have more experience?

• I want R (or other) code executed within my document: R Markdown with optional Bookdown

• I want a system with a large user base that is under active development: R Markdown with optional Bookdown, probably

• I want very smart appearance of an HTML website with minimal effort: Bookdown

• I want to convert existing LaTeX notes with minimal fiddling around: LaTeXML

• I want to produce HTML notes while learning minimal new stuff: LaTeXML

• The “bibles”:

  • R Markdown: The Definitive Guide
  • R Markdown Cookbook
  • bookdown: Authoring Books and Technical Documents with R Markdown

• My guide to R Markdown and Bookdown (a bit out of date)

• Serguei Komissarov’s guide to Bookdown

• Cosma Shalizi’s guide to R Markdown

• Source code for my MATH1710 notes

Locals I know of with R Markdown and/or Bookdown experience: Luisa Cutillo, Serguei Komissarov, Richard Mann, Graham Murphy, Jochen Voss, Phil Walker, …

Visit https://mpaldridge.github.io/rmarkdown/ for:

• These slides (with hyperlinks, and accessible by screenreaders)
• R Markdown source for these slides
• A handout, produced from exactly the same R Markdown source that made the slides themselves