Extend The Functionality OfYour R Markdown Document

class: center, middle, inverse, title-slide

# Extend The Functionality Of</br>Your R Markdown Document
### Christophe Dervieux
### userR!2021 - 08/07

---

# About me

.center[

.profile[![:scale 25%, profile picture for @cderv in Github](https://avatars.githubusercontent.com/u/6791940?v=4)]

RStudio &#8226; Software Engineer &#8226; R Markdown Team

]
.pull-left[
.center[
<svg aria-hidden="true" role="img" viewBox="0 0 496 512" style="height:1em;width:0.97em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg>
[@cderv](https://github.com/cderv)
]
]

.pull-right[
.center[
<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M459.37 151.716c.325 4.548.325 9.097.325 13.645 0 138.72-105.583 298.558-298.558 298.558-59.452 0-114.68-17.219-161.137-47.106 8.447.974 16.568 1.299 25.34 1.299 49.055 0 94.213-16.568 130.274-44.832-46.132-.975-84.792-31.188-98.112-72.772 6.498.974 12.995 1.624 19.818 1.624 9.421 0 18.843-1.3 27.614-3.573-48.081-9.747-84.143-51.98-84.143-102.985v-1.299c13.969 7.797 30.214 12.67 47.431 13.319-28.264-18.843-46.781-51.005-46.781-87.391 0-19.492 5.197-37.36 14.294-52.954 51.655 63.675 129.3 105.258 216.365 109.807-1.624-7.797-2.599-15.918-2.599-24.04 0-57.828 46.782-104.934 104.934-104.934 30.213 0 57.502 12.67 76.67 33.137 23.715-4.548 46.456-13.32 66.599-25.34-7.798 24.366-24.366 44.833-46.132 57.827 21.117-2.273 41.584-8.122 60.426-16.243-14.292 20.791-32.161 39.308-52.628 54.253z"/></svg>
[@chrisderv](https://twitter.com/chrisderv)
]
]

???

---
# What is this talk about ?

.pull-left.center[
![:scale 75%, rmarkdown package logo](https://pkgs.rstudio.com/rmarkdown/reference/figures/logo.png)
.f5[https://pkgs.rstudio.com/rmarkdown/]
]
.pull-right.center[
![:scale 55%, R Markdown Cookbook book cover](https://bookdown.org/yihui/rmarkdown-cookbook/images/cover.png)
.f5[https://bookdown.org/yihui/rmarkdown-cookbook/]
]

???

Everyone should know rmarkdown among R users. Its principle has not changed since a long time 
(md + R = Rmd -> output format) quite easy to start (write text, add code chunk, compile) but it can be harder to learn new skill to be more efficient and get full power.

That is where known recipes can help master more advanced skills. R Markdown Cookbook was thought as a non linear documentation

---
layout: true

# What happens when it renders ?

---

.center[![:scale 75%, R Markdown wizard illustration by Alison Horst](rmarkdown_wizards.png)]
.source-fig.center[Source: https://github.com/allisonhorst/stats-illustrations]

???

We often see these rmarkdown little wizard mixing Text & Code to produce document. Aim is to look deeper into this today. This is not so magic.

---

.box.f3[`knitr::knit()` + Pandoc (+ LaTeX for PDF) = `rmarkdown::render()`]

.center[![:scale 80%, Diagram showing the different step of rendering, using knitr first from Rmd to md, then Pandoc from md to output format like HTML, DOC and PDF (using LaTeX)](https://bookdown.org/yihui/rmarkdown-cookbook/images/workflow.png)]
.source-fig.center[
source: [R Markdown Cookbook](https://bookdown.org/yihui/rmarkdown-cookbook)
]

???

This is important to know so that one understand what to tweak to make something works

---
layout: true
# A simple default report

---

.center[
![:scale 90%, animated gif showing the content of the Rmd source for the default simple report without any tweak.](simple-report.gif)

.source-fig.right[
[RStudio Cloud project](https://rstudio.cloud/project/2646304) &#8226; [Download Rmd](https://user2021-enhanced-rmd.netlify.app/simple-report.Rmd)
]
]

---

.center[
![:scale 85%, animated gif showing the HTML output rendered from the previous simple report Rmd source. This HTML report use default content and style.](simple-report-html.gif)

.source-fig.right[
[RStudio Cloud project](https://rstudio.cloud/project/2646304) &#8226; [Download HTML](https://user2021-enhanced-rmd.netlify.app/simple-report.html)
]
]

---
layout: false

# Do not show source code block

.subtitle[knitr options `echo` and `include`]

````markdown
```{r setup, include=FALSE}
# do not show code by default
knitr::opts_chunk$set(echo = FALSE)
```
````
* Chunk will be evaluated but no output or source included.
* Do not show the source chunk as code block. Set globally here

---
layout: true
# Add alternative text

.subtitle[About `fig.alt` chunk option]

---

Can be used with an external image

````markdown
```{r species-img, fig.alt = "Illustration of pinguins species : Chinstrap, Gentoo and Adélia", out.width='60%', fig.align = 'center', echo = FALSE}
knitr::include_graphics("https://allisonhorst.github.io/palmerpenguins/reference/
figures/lter_penguins.png")
```
````
---

Or with R graphics

````markdown
```{r, include = FALSE}
island_repart_alt <- "Horizontal bar chart, faceted by Species showing the number of penguins living on each island, Torgersen, Dream and Biscoe. Adelie lives on the three, whereas Gentoo on Biscoe and Chinstrap on Dream."
```

*```{r island-repart, fig.alt= island_repart_alt}
ggplot(penguins, aes(x = island, fill = species)) +
  geom_bar(alpha = 0.8) +
  scale_fill_manual(values = c("darkorange","purple","cyan4"),
                    guide = FALSE) +
  theme_minimal() +
  facet_wrap(~species, ncol = 1) +
  coord_flip()
```
````

---
layout: true
# Style the output (1)

.subtitle[About the `css` engine]

---

````markdown
```{css, echo = FALSE}
/* header in blue */
h1, h2, h3 {
  color: #0A7FB2
}
```
````

Applied directly in the Rmd document without an external css file.

???

Useful with few CSS like with examples or prototyping for instance.
echo = false is important if you don't want to show CSS source chunk in output

---

Using external file :

````yaml
output:
  html_document:
    css: mystyle.css
````

Better suited to share style across documents.

???

---
layout: true
# Highlight results

.subtitle[Using Custom Blocks]

---

This is powered by [Pandoc's Fenced Divs](https://pandoc.org/MANUAL.html#divs-and-spans) syntax:

```markdown
::: {.highlight-box style="text-align: center;font-size: 1.5em;"}
The **`r heaviest_specie`** specie is heavier than other ! 
:::
```

---

This will be rendered in HTML

```html
<div class="highlight-box" style="text-align: center;font-size: 1.5em;">
<p>The <strong>Gentoo</strong> specie is heavier than other !</p>
</div>
```

---
layout: true
# Style the output (2)

---

.subtitle[How to improve our highlighted results ?]

> I want to .color1[**add a border**] to create a box and .color1[**apply my blue color**].

Can I use variable for color and limit duplication ?

---

.subtitle[Using SASS]

.center[![:scale 20%, SASS Language logo](https://sass-lang.com/assets/img/logos/logo-b6e1ef6e.svg)]

Sass (https://sass-lang.com) is a CSS extension language that allows you to create CSS rules in much more flexible ways than you would do with plain CSS.

???

It allows for variables, tweaking functions (called _mixins_), operations (like `/`), better CSS rule organisation (nesting, extensions, ...) and more.

---

.subtitle[Using SASS... from R]

.center[

![:scale 18%, Hex Logo of the sass R package.](https://rstudio.github.io/sass/reference/figures/logo.svg)</br>.f3[https://rstudio.github.io/sass/]
]

.box[Support is now built-in **rmarkdown**]

---

.subtitle[Using `sass` / `scss` knitr's engine]

.panelset[

.panel[.panel-name[css]

````markdown
```{css, echo = FALSE}
*h1, h2, h3 {color: #0A7FB2;}

div.highlight-box {
* border-color: #0A7FB2;
  border-style: solid;
  padding: 0.5em;
}

div.highlight-box strong {
* color: #0A7FB2;
}
```
````

]

.panel[.panel-name[scss]
````markdown
```{scss, echo = FALSE}
*$color1: #0A7FB2; /* using a variable */

*h1, h2, h3 {color: $color1;}

div { /* using nested organization */
  &.highlight-box { 
*   border-color: $color1;
    border-style: solid;
    padding: 0.5em;

*   strong {color: $color1;}
  }
}
```
````

]
.panel[.panel-name[sass]

````markdown
```{sass, echo = FALSE}
$color1: #0A7FB2

h1, h2, h3
  color: $color1

div
  &.highlight-box
    border-color: $color1
    border-style: solid
    padding: 0.5em
  
    strong
      color: $color1
```
````
]

]

???

_sass_ syntax is shorter (no `;` and `{ }`) but more different from _css_ than _scss_, so less easy to get started.

In this example and the previous _scss_ one, we are using special _SASS_ features like [Nesting](https://sass-lang.com/documentation/style-rules/declarations#nesting) and [Parent Selector](https://sass-lang.com/documentation/style-rules/parent-selector).

This allows organization of CSS rules for easier reading and modifications.

---

.subtitle[About our styled blue box]

The custom block we created

```mardkown
::: {.highlight-box style="text-align: center;font-size: 1.5em;"}
The **`r heaviest_specie`** specie is heavier than other ! 
:::
```
is now looking in our HTML this way
<style type="text/css">
div.highlight-box{border-color:#0A7FB2;border-style:solid;padding:0.5em}div.highlight-box strong{color:#0A7FB2}div.highlight-box p{margin:0}
</style>

.highlight-box.center[
The **Gentoo** specie is heavier than other !
]

---
layout: false

# A enhanced report

![:scale 80%, animated gif showing the resulting HTML report including all the changes mentioned previously.](simple-report-enhanced-html.gif)

.source-fig.right[
[RStudio Cloud project](https://rstudio.cloud/project/2646304) &#8226; [Download Rmd](https://user2021-enhanced-rmd.netlify.app/simple-report-enhanced.Rmd) &#8226; [Download HTML](https://user2021-enhanced-rmd.netlify.app/simple-report-enhanced.html)
]

---

# How to go further ?

.subtitle[and enhanced even more your Rmd !]

.pull-left[
.center[
![:scale 50%, R Markdown Cookbook online book cover](https://bookdown.org/yihui/rmarkdown-cookbook/images/cover.png)
]
]

.pull-right[