TALMO RMarkdown talk

# RMarkdown Primer

## Getting started, examples and a few tips

<hr>

### David Hodge
### Glasgow Caledonian University
### david.hodge@gcu.ac.uk

---

layout:true

background-image: url(images/GCUlogoP293.png)
background-position: 98% 2%
background-size: 150px
class: middle

---

## Target is HTML with MathJax (or MathML)

+ Alt text for images, figures and diagrams
+ Structure for screenreaders
+ Customizable display with browser-based accessibility software
+ "Responsive" (screen-size adaptability)
+ Want same quality of output as from LaTeX

### Option for dual output, also producing PDF via LaTeX

This forces certain writing approaches for displaying elements.

For example, when adding images only an R-chunk approach allows caption and alt text to be distinct.

Colouring of text needs extreme care too, in-built colours are not the same in HTML/CSS and Latex.

### Sample equation

`$$f(a) = \frac{1}{2\pi i} \oint\frac{f(z)}{z-a}dz$$`

---

## What are all these names?

### What is LaTeX?
 
1. Software (TeX and LaTeX) for converting text files to pretty output (PDF)
1. Syntax to describe formatting for the pretty output document (PDF)
1. **Syntax for equations which will be converted by the software (see above)**

### So what are Markdown and RMarkdown?

> A language used for creating formatted text from a plain-text editor.

There are now many variants of Markdown, RMarkdown is one of these file formats.

RMarkdown originated in users of R (and RStudio) but supports text containing code in many languages, including R, Python, Shell scripts, SQL, Javascript, CSS, Julia, C, Fortran and others. (See Jupyter talk later, and MyST Markdown)

???
This slide should be useful for anyone starting out on a journey away from "LaTeX"

---

## What does RMarkdown (Rmd) offer?

+ Excellent editor (RStudio) (**[Quick demo]**)
+ Rich community, support, forums, questions & answers.
+ Live code execution (R and others)
+ Many RMarkdown templates
+ Detailed documentation online
    - [RMarkdown manual](https://bookdown.org/yihui/rmarkdown/) (20 chapters)
    - [Bookdown manual](https://bookdown.org/yihui/bookdown/) (6 chapters)
    - [RMarkdown cookbook](https://bookdown.org/yihui/rmarkdown-cookbook/) (17 chapters)

Further customization via HTML styles (i.e. CSS) and templates (e.g. [Bootstrap](https://bootswatch.com/), Gitbook).

???
Syntax highlighting.
Show Hex colours.
LaTex previewing.

Package list: installation needed (Posit Cloud like Jupyter/Collab)
Similar to LaTeX that packages provide extra functionality but it's all done inside the RStudio editor.

---

---

## What does an RMarkdown file look like?

```text
---
*title: 'Maths notes'
*author: 'David Hodge'
*lang: en
*output:
*  html_document:
    css: 'mystyles.css'
    self-contained: true
    pandoc_args: ['--lua-filter=color-text.lua']
    mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js'    
*  pdf_document:
    pandoc_args: ['--lua-filter=color-text.lua']
    keep_tex: true
    toc: true
    latex_engine: xelatex
    includes:
      in_header: pream.tex
---
```
  ]

```text
## Re-arranging equations worksheet

This worksheet will contain some examples of equations for you to re-arrange.

Detailed solutions and explanations appear at the bottom.

### First examples

Try and make $x$ the subject of each of these equations.

(a) $$5+2x = 9+4x$$
(b) $$-3-2x = 8+2x$$
(c) $$3x+x \sin(t) = 4$$
(d) $$\frac{1}{1+x} = 3+y$$

...

```
  ]
  .panel[.panel-name[HTML output]

## Re-arranging equations worksheet

This worksheet will contain some examples of equations for you to re-arrange.

Detailed solutions and explanations appear at the bottom.

### First examples

Try and make `$x$` the subject of each of these equations.

(a) `$$5+2x = 9+4x$$`
(b) `$$-3-2x = 8+2x$$`
  ]
]

---

---

## Let's make an Rmd direct from the template

???
Open an Rmd from template

Do basic file. Add equation via dollars. Knit and Preview HTML.

Knit PDF, go find file and view it.

---

## What is bookdown?

+ Elaborate package for R/RStudio which adds a number of extra features

+ In particular for multi-page outputs (i.e. linked webpages, html books)

+ Standard template exists in RStudio &rarr; **[Head to RStudio for demo]**

### Benefits?

+ Enviroment numbering between files (i.e. theorems, equations, figures)

+ Easy to structure and navigate large sets of notes (e.g. for a whole module)

+ Can utilise existing HTML templates (Bootstrap, Gitbook etc... )

+ More details at [Bath's excellent webpages](https://teachinghub.bath.ac.uk/accessible-maths-with-rmarkdown-guidance/)

???
Demo by starting New Project. New directory.

Choose R bookdown.

Choose gitbook. Create project, look at files.

Compile and view.

---

## RMarkdown demo slide

Here is a recent example from my files:

+ **[Maths Summer Prereqs example HTML](https://edshare.gcu.ac.uk/10524/1/Level2-Prereqs.html)** ([PDF version](https://edshare.gcu.ac.uk/10524/1/Level2-Prereqs.pdf), [RMarkdown version](https://edshare.gcu.ac.uk/10524/1/Level2-Prereqs.rmd))

+ Also see various good links at Bath's website, such as [Vicky Scowcroft's introduction to bookdown](https://vickyscowcroft.github.io/bookdown_lecture_notes_guide/)

### Warning!

**Very few of guides specifically highlight accessibility, and discuss alt text, etc..**

---

## Fancier features demo

+ Bootstrap via Bookdown (bs4 demo) [MSS notes](https://tiny.cc/MSS-matrices)
+ Gitbook via Bookdown (gitbook includes an accessibility menu)
+ Rmd template galleries on github ([Search results](https://github.com/topics/rmarkdown-template))
+ Official outputs gallery [RStudio template gallery](https://rmarkdown.rstudio.com/gallery.html)

### Accessibility checking is not included

You may have your own favourites, but mine include:

+ Alt text viewer Chrome plug-in
+ Gitbook accessibility toolbar
+ Screen reader Chrome plug-ins (Read & Write)
+ WAVE evaluation toolp

---

## Live demo of creating an Rmd file

We will start from the standard HTML template file.

Here's a quick list of things I might have time to demonstrate:

+ Add an image (HTML only)
+ Add an image (Dual output) (more control including for alt text)
+ Change colour in text (HTML only)
+ Change colour in text (Dual) currently requires a script (Lua)
  - Use var(--name)
  - Add to tex pre-amble
  - Add to CSS as custom colour
+ Video embedding? Easiest to just use external sites.
  - But possible with HTML tags, just a little messy with captions

Custom enviroments for dual outputters:

+ Add theorem (HTML only) fenced divs
+ Add theorem (Dual) mention tex pre-amble

???
Take the plain HTML template. Remove all the content.

Save into TALMO directory (off home).
BigPalms.jpg is waiting for us.

Use !() notation.

Use R-Block notation. Mention fig.alt, fig.cap

---

## Resources

+ Enormous credit to Yihui Xie
+ RMarkdown & Bookdown websites
+ Many nice demo slides
+ Search stackexchange

---

## Final tips

Initial decisions:

+ 1 vs many files?
+ Re-use css across many projects? (Styles, fonts, custom ones, themes)
+ Dual vs HTML-only
+ Don't keep checking outputs (especially if dual)

---

# Thanks!

---

# Extra bonus slides

---

## Markdown demo

.pull-left[

### The markdown code

```text
+ Hello
+ Me

Here is a small equation:

$x^2+y^2=z^2.$
  
Or maybe a big equation,

$$\int_{0}^{\infty}e^{-x^2}\,\textrm{d}x$$

\begin{equation}x^2+y^2\label{eq:abc}\end{equation}

That previous equation is numbered \eqref{eq:abc}.

```
]

### The output

Here is a small equation:

`$x^2+y^2=z^2.$`
  
Or maybe a big equation,

`$$\int_{0}^{\infty}e^{-x^2}\,\textrm{d}x$$`

\begin{equation}x^2+y^2\label{eq:abc}\end{equation}

That previous equation is numbered \eqref{eq:abc}.

]

---

## R demonstration

### R code block

```r
for(i in 1:10){
  print(i)
}
```
]

### R code output

```
## [1] 1
## [1] 2
## [1] 3
## [1] 4
## [1] 5
## [1] 6
## [1] 7
## [1] 8
## [1] 9
## [1] 10
```
]

---

## Other topics - quick summary of options

+ Coloured text (messy for dual outputs)
  - In standard text (easy)
  - Inside equations (a little harder)
+ Video embedding
  - Via a link
  - Via typing html (needed for advanced features)
  - Via an RChunk, same as above really as R doesn't have video embedding
  - Via writing an R function to display link in PDF
  - See also https://rdrr.io/github/mccarthy-m-g/embedr/man/embed_video.html 
  - Use packages: htmltools and vembedr
+ Alt text
  - Via a link
  - Via typing HTML
  - Via an RChunk allows for more features
+ Colour schemes
  - Built-in templates / theming packages
  - Manually via CSS and colours