Who am I ?

Short intro

What are we talking today ?

What happens when it renders ?

Source: https://github.com/allisonhorst/stats-illustrations

What happens when it renders ?

knitr::knit() + Pandoc (+ LaTeX for PDF) = rmarkdown::render()

About the tools

We got you covered!

• rmarkdown 📦 will install knitr and tinytex for you
• Pandoc is an external binary tool, included inside RStudio IDE.
• TinyTeX is the only thing to install if you want PDF output. (tinytex::install_tinytex())

Let's dive now !

Source: https://github.com/allisonhorst/stats-illustrations

How to boost content creation ?

Read external scripts into a chunk

About the code chunk option (1)

add <- function(x, y) {
  x + y
}

```{r, code=xfun::read_utf8('my_script.R')}
```

```{r}
add <- function(x, y) {
  x + y
}
```

• This will fill the content of the chunk

• Can be used with any engine

• Can be used with multiple script

Chunk content from variable

About the code chunk option (2)

Ex: Installation instruction for packages.

```{r, include = FALSE}
pkgs <- c("glue", "fs")
installation_package <- sprintf('install.packages("%s")', pkgs)
```
```{r, eval = FALSE, code = installation_package}
```

renders without evaluating to

install.packages("glue")
install.packages("fs")

Read code chunks from a script

About knitr::read_chunk()

## ---- chunk-label

## ---- my-chunk-a --------
1 + 1
## ---- my-chunk-b --------
plot(cars)

Read an external script to load chunks:
```{r, include=FALSE, cache=FALSE}
knitr::read_chunk('my_script.R')
```
Now the code can be used chunk by chunk, e.g.,
```{r, my-chunk-a, echo=FALSE}
```
```{r, my-chunk-b, fig.height=4}
```

Use Rmd child document

About child chunk option

Load same content in several Rmd document

```{r common-setup, include = FALSE, child = "_common.Rmd"}
```

Conditionally include a content

Change `BOSS_MODE` to `TRUE` if this report is to be read
by the boss:
```{r, include=FALSE}
# variable impacting the rendering, which could be a parameter of a report
BOSS_MODE <- FALSE
```
Conditionally include the appendix:
```{r, child=if (!BOSS_MODE) 'appendix.Rmd'}
```

Dynamically create content

About knitr::knit_child()
(and result = 'asis')

## Regression on "`r x`"
```{r}
lm(mpg ~ ., data = mtcars[, c("mpg", x)])
```

```{r, echo=FALSE, results='asis'}
# select other variables than 'mpg'
x_vars <- setdiff(names(mtcars), 'mpg')
# knit the template for each
res <- lapply(x_vars, function(x) {
    knitr::knit_child('template.Rmd', 
    envir = environment(), quiet = TRUE
  )
})
# cat() the knitted output to be included 'asis' 
cat(unlist(res), sep = '\n')
```

```{r, echo=FALSE, results='asis'}
x_vars <- setdiff(names(mtcars), 'mpg')
res <- lapply(x_vars, function(x) {
   knitr::knit_child(text = c(
    '## Regression on "`r x`"',
    '',
    '```{r}',
    'lm(mpg ~ ., data = mtcars[, c("mpg", x)])',
    '```',
    ''
  ), envir = environment(), quiet = TRUE)
})
cat(unlist(res), sep = '\n')
```

Reuse a chunk

About chunk label

Here is a code chunk that is not evaluated:
```{r, chunk-one, eval = FALSE}
1 + 1
2 + 2
```
Now we actually evaluate it:
```{r, chunk-one, eval = TRUE}
```

First chunk will be used twice - different options are allowed.

Use labels to reference chunks

About chunk ref.label

```{r chunk-b, echo = FALSE}
# this is the chunk b
1 + 1
```
```{r chunk-c, echo = FALSE}
# this is the chunk c
2 + 2
```
```{r chunk-a, ref.label = c('chunk-c', 'chunk-b'), eval = FALSE}
```

```{r chunk-a, eval = FALSE}
# this is the chunk c
2 + 2
# this is the chunk b
1 + 1
```

```
## [1] 2
```
```
## [1] 4
```
```r
# this is the chunk c
2 + 2
# this is the chunk b
1 + 1
```

How to boost output styling ?

Use CSS from inside a Rmd file

About the css engine

```{css, echo = FALSE}
/* add a blue border */
div.mybox {
  border-color: blue;
  border-style: solid;
  padding: 0.5em;
}
/* Set to blue bold text inside the box */
div.mybox strong {
  color: blue;
}
```

Applied directly in the Rmd document without an external css file

Going further: See the js engine to apply JS code the same way

Use SASS the same way

About the sass/scss engine

What is SASS ?

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.

Use SASS the same way

About the sass/scss engine

```{css, echo = FALSE}
div.mybox {
  border-color: blue;
  border-style: solid;
  padding: 0.5em;
}
div.mybox strong {
  color: blue;
}
```

```{scss, echo = FALSE}
$color1: blue;
div {
  &.mybox {
    border-color: $color1;
    border-style: solid;
    padding: 0.5em;
    strong {
      color: $color1;
    }
  }
}
```

```{sass, echo = FALSE}
$color1: blue
div
  &.mybox
    border-color: $color1
    border-style: solid
    padding: 0.5em
    strong
      color: $color1
```

Use SASS the same way

Powered by the new sass R 📦

Use SASS the same way

Powered by the new sass R 📦

$color1: blue
div
  &.mybox
    border-color: $color1
    border-style: solid
    padding: 0.5em
    strong
      color: $color1

# Rendering SASS file from R
sass::sass(sass::sass_file("style.sass"))

div.mybox {
  border-color: blue;
  border-style: solid;
  padding: 0.5em;
}
div.mybox strong {
  color: blue;
}

Use SASS the same way

Powered by the new sass R 📦

External .sass / .scss file can also be passed in the css argument of html_document()

output:
  html_document:
    css: custom-style.scss

The file will be processed internally by sass::sass_file() and produce a .css automatically.

Use custom blocks to style

Powered by Pandoc's fenced divs syntax

::: mybox
Special **important** content
:::

With the previous style applied, it will result in this box in the document

<div class="mybox">
<p>Special <strong>important</strong> content</p>
</div>

Use custom blocks to style

Powered by Pandoc's fenced divs syntax

Attributes and id can be added too, e.g

::: {.mybox #box1 style="text-align: center;"}
Special **important** content
:::

The above add inline style to the div

<div id="box1" class="mybox" style="text-align: center;">
<p>Special <strong>important</strong> content</p>
</div>

???

Allow to style mainly.

Aiming multi formats

About rmarkdown custom blocks for PDF support

::: {.mybox latex=true}
Special **important** content
:::

\begin{mybox}
Special \textbf{important} content
\end{mybox}

Specially supported by R Markdown and not Pandoc.

Create a LaTeX environment as easily as you can create a HTML div.

Aiming multi formats

About rmarkdown custom blocks for PDF support

This requires a LaTeX preamble for this custom environment to render to PDF, e.g using tcolorbox CTAN package.

\usepackage{tcolorbox}
\newtcolorbox{mybox}{
  colframe=blue,
  halign=center,
  boxsep=5pt,
  arc=4pt}

To pass to the output format, e.g

output: 
  pdf_document:
    includes:
      in_header: preamble.tex

Aiming multi formats

About rmarkdown custom blocks for PDF support

Using the cat engine can help you write the preamble from within the Rmd file

```{cat, engine.opts = list(file = 'preamble.tex')}
\usepackage{tcolorbox}
\newtcolorbox{mybox}{
  colframe=blue,
  halign=center,
  boxsep=5pt,
  arc=4pt}
```

This will result in the PDF as this box

What we've learn so far ?

Let's sum up!

Create content without repeating yourself

• Import code chunk content from a script or from a variable
• Use Rmd child document to share content in several places
• Reuse some chunks several times

Customize output style

• Customize HTML output using CSS and SASS code
• Create and style custom blocks for HTML and PDF allowing better customization

How to go further ?

and boost even more your skills !