Customizing R Markdown

# Customizing R Markdown
## R-Ladies St. Louis 
### Mine Çetinkaya-Rundel
### <a href="https://bit.ly/custom-rmd-stl">bit.ly/custom-rmd-stl</a>

---

# R ❤️ Markdown sitting in a tree

# K-I-S-S-I-N-G

---

## What is Markdown?

- Lightweight markup language with plain text formatting syntax

- Designed so that it can be converted to HTML (and many other formats)

---

## What is R Markdown?

- Markdown + R

- Text + R code (in chunks) gets converted to text + R code + R output in HTML (and many other formats)

---

## Options for hands on activities

- Go to [bit.ly/custom-rmd-stl-cloud](https://bit.ly/custom-rmd-stl-cloud), create an account/log in, save a permanent copy of the project

- Go to [github.com/rladiesstl/intro-meetup4-oct-2021/](https://github.com/rladiesstl/intro-meetup4-oct-2021/), clone the repo, follow along in `exercises/`

---

## demo: `01-rmd-simple.Rmd`

---

# Aside: Visual editor

---

## Visual editor

.pull-left[
- Visual editing for all of text, tables, lists, etc.
- Support for citations
- Cross-refs, footnotes, equations, LaTeX
]
.pull-right[
- Real time spell-checking, outline navigation
- Tight integration with source editing
- Insert anything with catch-all `⌘ /` shortcut
]

---

## demo: `02-visual-editor.Rmd`

---

# Customizing .brown[chunk options]

---

## Show / hide

- `message = FALSE` and `warning = FALSE` to suppress messages and warnings (with caution!)
- `error = TRUE` to knit despite an error
- `include = FALSE` to run, but hide output, messages, warnings, etc.

---

## Chunk options for figures

- Recommended chunk options:
  - `fig.retina = 3`
  - `out.width = "70%"`
  - `fig.width = 6`
  - `fig.asp = 0.618`
  - `fig.alt`: Alternative text
- More on this:
  - [R for Data Science - Graphics for communication](https://r4ds.had.co.nz/graphics-for-communication.html)
  - [Tips and tricks for working with images and figures in R Markdown documents](https://www.zevross.com/blog/2017/06/19/tips-and-tricks-for-working-with-images-and-figures-in-r-markdown-documents/)

---

## Setting global options

```r
knitr::opts_chunk$set(
  fig.retina = 3,
  out.width = "70%",
  fig.width = 6,
  fig.asp = 0.618
)
```

---

## demo: `03-chunk-options.Rmd`

---

# Customizing .brown[output]

---

## Same input, different outputs

with a simple change in the YAML

```r
output: html_document
output: pdf_document
output: word_document
output: tufte::tufte_html
...
```

---

## demo: `04-outputs.Rmd`

---

# Customizing .brown[theme]

---

## Change output options

---

## bslib & thematic

- [**bslib**](https://rstudio.github.io/bslib/): Tools for customizing [Bootstrap themes](https://getbootstrap.com/docs/4.6/getting-started/theming/) directly from R, making it much easier to customize the appearance of Shiny apps & R Markdown documents

- [**thematic**](https://rstudio.github.io/thematic/): Simplified theming of ggplot2, lattice, and base R graphics, automatically styled in R Markdown documents (and Shiny apps, and in the RStudio IDE)

---

## demo: `05-theme.Rmd`

---

# Customizing .brown[format]

---

## Same-ish source, different format

Using R Markdown, you can write

- books: **bookdown**
- websites: **blogdown**, **distill**, **pkgdown**
- slide decks: **xaringan**
- dashboards: **flexdashboard**
- ...

---

```r
countdown(minutes = 0, seconds = 30)
```

---

## demo: `06-xaringan.Rmd`

---

# Learn .brown[more]

---

---

.center[
.midi[
[rstudio.com/resources/cheatsheets/](https://www.rstudio.com/resources/cheatsheets/)
]
]

---

## Acknowledgements

- RStudio R Markdown team + community
- RStudio cheat sheets intern Averi Perny
- Fernando Campos for the [**ramboseli**](https://github.com/amboseli/ramboseli) package (and Jenny Tung for the pointer!)

---