Business Reports with R Markdown

class: center, middle, inverse, title-slide

# Business Reports with R Markdown
## How to better theme report ?
### Christophe Dervieux
### <p>R Enterprise Meetup - 05/10/2021<br> <img class="title" width="25%" src="https://www.rstudio.com/wp-content/uploads/2018/10/RStudio-Logo-white.svg"></p>

---

<div>
<style type="text/css">.xaringan-extra-logo {
width: 150px;
height: 52.5px;
z-index: 0;
background-image: url(https://www.rstudio.com/wp-content/uploads/2018/10/RStudio-Logo-flat.svg);
background-size: contain;
background-repeat: no-repeat;
position: absolute;
bottom:1em;left:1em;
}
</style>
<script>(function () {
  let tries = 0
  function addLogo () {
    if (typeof slideshow === 'undefined') {
      tries += 1
      if (tries < 10) {
        setTimeout(addLogo, 100)
      }
    } else {
      document.querySelectorAll('.remark-slide-content:not(.title-slide):not(.inverse):not(.hide_logo)')
        .forEach(function (slide) {
          const logo = document.createElement('a')
          logo.classList = 'xaringan-extra-logo'
          logo.href = 'https://www.rstudio.com'
          slide.appendChild(logo)
        })
    }
  }
  document.addEventListener('DOMContentLoaded', addLogo)
})()</script>
</div>

# Who am I ?

.subtitle[Short intro]

.center[

.profile[![:scale 20%, profile picture for Christophe Dervieux](https://avatars.githubusercontent.com/u/6791940?v=4)]

Christophe DERVIEUX &#8226; France

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

]
</br>
.pull-left[
.center[
.f2.color1[<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>]</br>
[@cderv](https://github.com/cderv)
]
]

.pull-right[
.center[
.f2.color1[<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>]</br>
[@chrisderv](https://twitter.com/chrisderv)
]
]

???

---
# What are we talking today ?

.center-middle[

> I work in an organization with some styling guidelines and I would like to use them on my R Markdown document. 
> 
> How does that work ?

.center.pv4.big[Let's discuss about styling with R Markdown !]

]

???

Guidelines are usually colors, fonts, size but can also be document template.

We'll try cover most formats from HTML to Office Document

---
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. It is juts perceived magic and there are tools to know about under the hood to be able to customize behavior further. And it is important to know about this for styling.

---

.center[![:scale 75%, 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)
]

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

???

rmarkdown will run Pandoc & knitr for you so one input for multiple output possible. 
But stylings is specific to the output.

This is important to know all this because it helps know where to look and what could be tweak. one has to understand what to tweak to make something works as expected.

---
layout: false
class: inverse

.center[![:scale 65%, Gif of a man in a suits putting a a pink hat with included sunglasses. Text on the gif says 'You don't like my style', then 'Deal with it'](https://media.giphy.com/media/14o3gppq0mt2Lu/giphy.gif)]

???

Let's talk about styling content now.

---
class: inverse middle

# Working with HTML output

---
# Styling with CSS

.subtitle[Cascading Stylesheets]

## What is CSS ?

.center-middle[
> While **HTML** is used to define the **structure and semantics** of your content, **CSS** is used to **style it and lay it out**.  
> For example, you can use CSS to alter the font, color, size, and spacing of your content, split it into multiple columns, or add animations and other decorative features.

.source-fig.center[Source: https://developer.mozilla.org/en-US/docs/Learn/CSS]

.box[
  .ma3[
    Styling HTML output will require more or less CSS skills
  ]
]
]

???

If you have those skills, here what you can do

---

# Use CSS from inside a Rmd file

.subtitle[About the `css` chunk engine]

````markdown
```{css, echo = FALSE}
/* add a blue border */
div.mybox {
  border-color: blue;
  border-style: solid;
  padding: 0.5em;
  text-align: center;
}

/* Set to blue bold text inside the box */
div.mybox strong {
  color: blue;
}
```
````

Applied directly in the Rmd document without an external css file

???

Useful for prototyping, for quick iteration, for single file example
echo = false is important if you don't want to show CSS source chunk in output

You can also use the `css` argument of `html_document()`

But with CSS files it can be hard to create theme file you can reuse.

Enter SASS

---
layout: true
# Use SASS the same way

.subtitle[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.
</br>
</br>
.center[![:scale 20%](https://sass-lang.com/assets/img/logos/logo-b6e1ef6e.svg)]

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

???

**NEW WAY**

External tool used by web developers. Very powerful and this is a skill to learn when doing a lot of HTML. It can do a lot !

But no need to use it directly. Still need to learn the feature and syntax.

---
.panelset[

.panel[.panel-name[previous css]

````markdown
```{css, echo = FALSE}
div.mybox {
* border-color: blue;
  border-style: solid;
  padding: 0.5em;
  text-align: center;
}

div.mybox strong {
* color: blue;
}
```
````

]

.panel[.panel-name[scss]
````markdown
```{scss, echo = FALSE}
*$color1: blue;

div {
  &.mybox {
*   border-color: $color1;
    border-style: solid;
    padding: 0.5em;
    text-align: center;

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

???

The CSS is the one that would be render when using sass on the .scss or .sass file.

No preference on the syntax - it is a personnal choice (and depending on environment.)

---
layout: true
# Use SASS the same way

.subtitle[Powered by the new **sass** R 📦]

---

.center[

![:scale 25%](https://rstudio.github.io/sass/reference/figures/logo.svg)

https://pkgs.rstudio.com/sass/

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

]

???

Quite new. Allow to use SASS from R. Wrapper around a C library.

Supported in rmarkdown now.

---

External `.scss` file can also be passed in the `css` argument of most output format like `html_document()`

</br>

````yaml
output:
  html_document:
    css: custom-style.scss
````

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

.box[Using a `.scss` file makes it easier to use variables and rules in CSS.  
Use variables to store style guide values and use theme in several places.]

???

You can do much more with SASS. It pushes the limit of customization of a document.

You can easily apply style on component identified by class or id, attributes.

HTML is the way to structure but Pandoc Markdown will simplify that.

---
layout: true

# Apply custom style on specific component

.subtitle[Powered by Pandoc Markdown syntax]

---

Creating custom blocks (using Pandoc's Fenced Divs)

```markdown
::: mybox
Special **important** content
:::
```

.mybox-demo strong {
  color: blue;
}
</style>

.pb3[
With the previous style applied, it will result in this box in the document
]
.pb3[
.mybox-demo[
Special **important** content
]
]

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

???

Pandoc feature. R Markdown knows and extend it. 
Quite simple to write but quite powerful.

Supported by Visual editor.

---

Using attributes on element works too (with Pandoc's Bracketed Spans)

```markdown
[This is *some text*]{.my-bg-blue lang="en"}
```

Applying this style:

```css
.my-bg-blue {
  background: lightblue;
}
```

will result in:

.my-bg-blue[This is *some text*]

```html
<p><span class="my-bg-blue" lang="en">This is <em>some text</em></span></p>
```

---
layout: false

# Going further with Bootstrap

.subtitle[Powered by the new **bslib** R 📦]

[**bslib**](https://pkgs.rstudio.com/bslib) provides tools for customizing [Bootstrap](https://getbootstrap.com/) themes directly from R. It allows take custom theming easier and provide easy access to pre-packaged Bootswatch themes.

.pull-left[
Supported in R Markdown output format:
* `rmarkdown::html_document()` .small[(using `theme` argument)]
* `flexdashboard::flex_dashboard()` .small[(current dev version > 0.5.2)]
* `bookdown::bs4_book()` built on Bootstrap 4
]

.pull-right[
Supported in other tools:
* **DT** (since 0.18)
* **shiny** (since 1.6.0)
* **pkgdown** (current dev version > 1.6.1)
]

**rmarkdown** still doesn't use **bslib** by default: Simple example to activate Bootstrap 4 in `html_document()` with **bslib** and default style

.fl.w-third.ph1[
```yaml
# Using bootswatch rmarkdown theme, 
# with included Bootstrap 3 (not bslib)
output:
  html_document:
    theme: cerulean
```
]
.fl.w-third.ph1[
```yaml
# Activate the use of bslib, 
# with Bootstrap version 4 and not bootswatch theme
output:
  html_document:
    theme: 
      version: 4
```
]
.fl.w-third.ph1[
```yaml
# Activate the use of bslib, 
# with Bootstrap version 4 and bootswatch theme
output:
  html_document:
    theme: 
      bootswatch: cerulean
```
]

???

---
layout: true

# How does that work ?

.subtitle[Showing a full example]

---

Using variables in YAML instead of a `.scss` file...

```yaml
output:
  html_document:
    theme:
      primary: "#4D8DC9"                 # Changing primary color to blue
      secondary: "#4D4D4D"               # Changing secondary to grey
      blockquote-border-color: "#FDBE4B" # Styling specific blockquote part to yellow
      lightblue: "#75AADB"               # definining another blue as variable to reuse
      code-color: "$lightblue"           # inline code color will be blue
      border-color: "$lightblue"         # as default border color
      border-width: "3px"                # increasing border width
      warning: "#E7553C"                 # warning-like text will be orange 
      info: "#A4C689"                    # info like text will be green
      headings-font-weight: 900          # increasing heading font weight
      base_font:
        google: "Prompt"                 # changing base font 
      code_font:
        google: "JetBrains Mono"         # changing code font
```
---

...to get a customized document following specific style

.fl.w-90[
.center[![:scale 68%, Screenshot of resulting html document using previous yaml header](style-based-bootstrap.png)]
]
.fl.w-10[
.small[
Demo file: 
  * [Source Rmd](styling-bootstrap.Rmd)
  * [HTML output](styling-bootstrap.html) ]
]

???

Bootstrap is not for all outputs (xaringan, reveal, tufte, does not use for example)

We aim at making that even easier by creating a common theming system for all outputs where you could easily define vairables and rules and apply theme across output.

---
layout: false

# Useful resources

.subtitle[Going further with HTML styling in R]

.pv5[
* Customizing **flexdashboard** (development version): https://pkgs.rstudio.com/flexdashboard/articles/theme.html

* Styling new `bookdown::bs4_book()`: https://bookdown.org/yihui/bookdown/html.html#bs4-book

* Using **bslib**: https://pkgs.rstudio.com/bslib

* Using **sass**: https://pkgs.rstudio.com/sass

* Styling  **pkgdown** (development version): https://pkgdown.r-lib.org/dev/articles/customization.html

]

---
class: inverse middle

# Working with Office document

---
layout: true

# Styling Word and Powerpoint

---
.subtitle[Using template reference document]

Using a reference document as template with R Markdown

.fl.w-50.pr4[
```yaml
output:
  word_document:
    reference_doc: template.docx
```
]

.fl.w-50.pl4[
```yaml
output:
  powerpoint_presentation:
    reference_doc: template.pptx
```
]

.underline[One way to create a template:]

1. Render once without reference document

1. Save the resulting output as the reference doc

1. Modify the reference document to customize according to your style

1. Use the document as reference doc

---

.subtitle[How to customize a default template ?]

.center[
![:scale 70%](change-style-in-word.png)
]

???

Example with Word Document

You can customize default style set in Headers, paragraph or else.

---

.subtitle[How to apply custom style ?]

Using [Div & Spans](https://pandoc.org/MANUAL.html#divs-and-spans) from Pandoc Markdown syntax.

.fl.w-50.pr5[
Using fenced div attributes  
for Paragraph style
````markdown
::: {custom-style="highlight-box"}
The **`r heaviest_specie`** specie is heavier than other ! 
:::
````
]

.fl.w-50.pl5[
Using Spans attributes  
for Text style:
```markdown
[One of the species lives on all islands]{custom-style="Emphatically"} and the others are specific to one island only. 
```
]

This will associate Docx Styles name to the text. Style can then be modified in template.

.fl.w-50[
Documentation: 
  * [Pandoc Manual about Custom Styles](https://pandoc.org/MANUAL.html#custom-styles)
  * [Style name to tweak](https://pandoc.org/MANUAL.html#option--reference-doc)
]
.fl.w-50[
Examples:
  * [Rmd source](pinguins-report.Rmd)
  * [Docx template](template.docx)
  * [Docx output](pinguins-report.docx)
]
---

.subtitle[Limitations & Beyond]

.f3.color1.b[It is powered by Pandoc]

* We're limitated by their features - not everything can be customized.
* But we worked this summer with Pandoc team to improve Powerpoint templating mechanism.

.f3.color1.b[Unfortunatly, styling Office Document is not easy (through Pandoc or not)]

* One must know about Office Style system
* Simple customization works, more complex may not

.f3.color1.b[Other great tools for R users]

.fl.w-third.center[![:scale 50%](https://ardata-fr.github.io/officeverse/illustrations/officerlogo.svg)]
.fl.w-third.center[![:scale 50%](https://ardata-fr.github.io/officeverse/illustrations/officedown.svg)]
.fl.w-third.center.pt5[
Officeverse by David Gohel  
.small[https://ardata-fr.github.io/officeverse]]

---
layout: false
class: inverse middle

# Working with PDF document

---
layout: true

# What about PDF output ?

---

.subtitle[Producing PDF]

## Creating PDF through LaTeX

Styling needs to be done using TeX styling mechanism, with help of CTAN packages.

## Creating PDF through HTML

🎉 CSS can be used !

Two solutions:

1. Printing document as-is

2. Formating and Styling HTML specifically for printing (using Paged Media CSS)

---

.subtitle[About Paged Media CSS with R]

.flex.items-center[
.w-25[
.center[![:scale 50%](https://raw.githubusercontent.com/rstudio/hex-stickers/master/SVG/pagedown.svg)]
]
.w-75[
Paginate the HTML Output of R Markdown with CSS for Print
.center[https://github.com/rstudio/pagedown]
]
]

.pv3[
**pagedown** brings [Paged.js](https://www.pagedjs.org/) to R, a free and open source JavaScript library that paginates content in the browser to create PDF output from any HTML content.
]

.box[
📽 .color1[RSTUDIO::CONF 2019 Talk by Yihui Xie] 📽  
[pagedown: Creating beautiful PDFs with R Markdown and CSS (RSTUDIO::CONF 2019) ](https://www.rstudio.com/resources/rstudioconf-2019/pagedown-creating-beautiful-pdfs-with-r-markdown-and-css/)

and more examples in Github README
]

???

**pagedown** is the tool to make paginated HTML from R but designing paged report can be tricky.

---

.subtitle[Simplify the use of **pagedown** through templates]

.fl.w-30[
![:scale 100%](https://rfortherestofus.com/wp-content/uploads/2021/01/windmill.gif)
]
.fl.w-70.pa3[
Enter **pagedreport** 📦  
by Thomas Vroylandt and David Keyes

.center.small[[Announcing pagedreport](https://rfortherestofus.com/2021/01/announcing-pagedreport/)   •   [Docs](https://pagedreport.rfortherestofus.com/)]

* Uses R Markdown to produce PDF using **pagedown**

* Offers some template than can be tweak easily
  * Colors
  * Fonts
  * Covers
  * Logo
  
]

---
layout: false

# What we've learn so far ?

.subtitle[Let's sum up!]

.pv4[
* .color2[**Customize HTML output**] using CSS, SASS or Bootstrap variables with **bslib**

* .color2[**Using templates**] for Office outputs using Pandoc

* .color2[**Create and style custom blocks**] for HTML and office outputs using Pandoc Markdown

* .color2[**Create PDF from HTML**] to benefit from CSS styling

* .color2[**Paginated HTML is a thing**], and can be done from R using **pagedown**

]

.center[![:scale 30%](https://media.giphy.com/media/S8Bnf6KByXDly5VCzq/giphy.gif)]

---
class: center middle inverse

# Thank you !

.f2.white[<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>]</br>https://github.com/cderv/meetup-2021-rmd-business-report