Extending Rmarkdown

class: right, middle, title-slide

.title[
# <code>Extending Rmarkdown</code>
]
.subtitle[
## 
]
.author[
### Nicolas CASAJUS .inst[nicolas.casajus at fondationbiodiversite.fr]
]
.date[
### .inst[Mardi 29 novembre 2022]
]

---

## Table of contents

.medium[
.pull-left[
1. Tips and Tricks
  - Child
  - `knitr::read_chunks()`
  - params
  - Figures & Tables
]

.pull-right[
**Output formats**

- Reports (`HTML`, `PDF`, `DOCX`, `GitHub Document`)
- Presentations (`xaringan`, `reveal.js`, `PPTX`)
- Scientific articles (`rticles`)
- Websites (`blogdown`, `distill`, `pkgdown`)
- Books (`bookdown`)
- Dashboards
- GitHub Pages (for HTML outputs)

**Bibliography**

- RStudio & Zotero
- Zotero styles
- `nocite: '@*'`

**Theming**

- Default themes
- Extensions
- Custom blocks

**Miscellaneous**

- Break list ``
- Hard line break `\ `, ` `, `\newline`
]
]
---

## Chunks options

Usual way:

````r
```{r 'chunk-name', echo=FALSE, fig.width=10, fig.cap='This is a long long long long caption.'}

x <- 1 + 2
print(x)
```
````

```
## [1] 3
```

Alternatively:

````r
```{r}
#| 'chunk-name',
#| echo = FALSE,
#| fig.width = 10,
#| fig.cap = 'This is a long long
#|   long long caption.'

x <- 1 + 2
print(x)
```
````

```
## [1] 3
```

.medium[ Quarto uses this syntax]

---

## Global chunks options

Do not repeat same chunk options values across all chunks. Use instead a general
chunk that will provide default values for all chunks.

````r
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE, eval = TRUE, message = FALSE,
                      fig.width = 10, fig.height = 8, ...)
```
````

You will be able to change locally (for specific chunk) the default value:

````r
```{r 'chunk-name', echo = TRUE}
1 + 3
```
````

```r
1 + 3
```

```
## [1] 4
```

---

## Rmd with others languages

.pull-left[
**R code** -

````r
```{r}

person <- "Jane Doe"
paste0("Hello, ", person, "!")
```
````

```
## [1] "Hello, Jane Doe!"
```
]

---

## Rmd with others languages

.pull-left[
**R code** -

````r
```{r}

person <- "Jane Doe"
paste0("Hello, ", person, "!")
```
````

```
## [1] "Hello, Jane Doe!"
```

**Bash code** -

````r
```{bash}
#| engine.path='/bin/bash'

person="Jane Doe"
echo "Hello"$person"!"
```
````

```
## Hello, Jane Doe!
```
]

.pull-right[
**Python code** -

````r
```{python}
#| engine.path='/usr/local/bin/python3'

person <- "Jane Doe"
f"Hello, {person}!"
```
````

```
## 'Hello, Jane Doe!'
```

**Ruby on Rails code** -

````r
```{ruby}
#| engine.path='/usr/bin/ruby'

person = "Jane Doe"
puts "Hello, " + person + "!"
```
````

```
## Hello, Jane Doe!
```
]

```r
Sys.which("python3")        ## Locate the Python3 engine (binary)
```

```
##                  python3 
## "/usr/local/bin/python3"
```

---

## Rmd with others languages

A smarter approach: use the global chunks options of `knitr`.

```r
## Global options ----
knitr::opts_chunk$set(engine.path = list(python = "/usr/local/bin/python3"))
```

And then,

````r
```{python}

person <- "Jane Doe"
f"Hello, {person}!"
```
````

```
## 'Hello, Jane Doe!'
```

---

## Resources

.medium[
- [**R Markdown Advanced Tips**](https://www.youtube.com/watch?v=WkF7nqEYF1E)
 Video by **Tom Mock**

- [**Meta RMarkdown - Taxonomy and Use cases**](https://themockup.blog/posts/2020-07-25-meta-rmarkdown/)
 Blogpost by **Tom Mock**

- [**R Markdown Cookbook**](https://bookdown.org/yihui/rmarkdown-cookbook/)
 Online book by **Yihui Xie et al.**

- [**R Markdown: The Definitive Guide**](https://bookdown.org/yihui/rmarkdown/)
 Online book by **Yihui Xie et al.**

- [**Dynamic Documents with R and knitr**](https://duhi23.github.io/Analisis-de-datos/Yihue.pdf)
 Online book by **Yihui Xie**

- [**blogdown: Creating Websites with R Markdown**](https://bookdown.org/yihui/blogdown/)
 Online book by **Yihui Xie et al.**

- [**bookdown: Authoring Books and Technical Documents with R Markdown**](https://bookdown.org/yihui/bookdown/)
 Online book by **Yihui Xie**
]

---

## Custom blocks

.pull-left[
**In the `.Rmd` file**

```
::: {.box-info}
Lorem ipsum dolor sit amet, consectetur adipiscing 
elit. Suspendisse at mattis libero. Vestibulum 
ante ipsum primis in faucibus...
:::
```
]

.pull-right[
**CSS style**
```css
div.box-info p {
  padding: 1em;
  margin: 20px 0;
  background: #DDECF6;
  border: 1px solid #CEE9F2;
  border-radius: 10px;
  color: #487997;
  border-left: 5px solid #487997;
}
```
]

.center[![:scale 75%](img/custom-blocks.png)]

.medium[Example: <**https://github.com/rdatatoolbox/rmd-examples/custom-blocks/index.Rmd**>]