class: center, middle, inverse, title-slide # Presentation Ninja ## ⚔<br/>with xaringan ### Yihui Xie ### RStudio, PBC ### 2016/12/12 (updated: 2021-11-01) --- background-image: url(https://upload.wikimedia.org/wikipedia/commons/b/be/Sharingan_triple.svg) ??? Image credit: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Sharingan_triple.svg) --- class: center, middle # xaringan ### /ʃaː.'riŋ.ɡan/ --- class: inverse, center, middle # Get Started --- # Hello World Install the **xaringan** package from [Github](https://github.com/yihui/xaringan): ```r remotes::install_github("yihui/xaringan") ``` -- You are recommended to use the [RStudio IDE](https://www.rstudio.com/products/rstudio/), but you do not have to. - Create a new R Markdown document from the menu `File -> New File -> R Markdown -> From Template -> Ninja Presentation`;¹ -- - Click the `Knit` button to compile it; -- - or use the [RStudio Addin](https://rstudio.github.io/rstudioaddins/)² "Infinite Moon Reader" to live preview the slides (every time you update and save the Rmd document, the slides will be automatically reloaded in RStudio Viewer. .footnote[ [1] 中文用户请看[这份教程](https://slides.yihui.org/xaringan/zh-CN.html) [2] See [#2](https://github.com/yihui/xaringan/issues/2) if you do not see the template or addin in RStudio. ] --- background-image: url(https://github.com/yihui/xaringan/releases/download/v0.0.2/karl-moustache.jpg) background-position: 50% 50% class: center, bottom, inverse # You only live once! --- # Hello Ninja As a presentation ninja, you certainly should not be satisfied by the "Hello World" example. You need to understand more about two things: 1. The [remark.js](https://remarkjs.com) library; 1. The **xaringan** package; Basically **xaringan** injected the chakra of R Markdown (minus Pandoc) into **remark.js**. The slides are rendered by remark.js in the web browser, and the Markdown source needed by remark.js is generated from R Markdown (**knitr**). --- # remark.js You can see an introduction of remark.js from [its homepage](https://remarkjs.com). You should read the [remark.js Wiki](https://github.com/gnab/remark/wiki) at least once to know how to - create a new slide (Markdown syntax^* and slide properties); - format a slide (e.g. text alignment); - configure the slideshow; - and use the presentation (keyboard shortcuts). It is important to be familiar with remark.js before you can understand the options in **xaringan**. .footnote[[*] It is different with Pandoc's Markdown! It is limited but should be enough for presentation purposes. Come on... You do not need a slide for the Table of Contents! Well, the Markdown support in remark.js [may be improved](https://github.com/gnab/remark/issues/142) in the future.] --- background-image: url(https://github.com/yihui/xaringan/releases/download/v0.0.2/karl-moustache.jpg) background-size: cover class: center, bottom, inverse # I was so happy to have discovered remark.js! --- class: inverse, middle, center # Using xaringan --- # xaringan Provides an R Markdown output format `xaringan::moon_reader` as a wrapper for remark.js, and you can use it in the YAML metadata, e.g. ```yaml --- title: "A Cool Presentation" output: xaringan::moon_reader: yolo: true nature: autoplay: 30000 --- ``` See the help page `?xaringan::moon_reader` for all possible options that you can use. --- # remark.js vs xaringan Some differences between using remark.js (left) and using **xaringan** (right): .pull-left[ 1. Start with a boilerplate HTML file; 1. Plain Markdown; 1. Write JavaScript to autoplay slides; 1. Manually configure MathJax; 1. Highlight code with `*`; 1. Edit Markdown source and refresh browser to see updated slides; ] .pull-right[ 1. Start with an R Markdown document; 1. R Markdown (can embed R/other code chunks); 1. Provide an option `autoplay`; 1. MathJax just works;^* 1. Highlight code with `{{}}`; 1. The RStudio addin "Infinite Moon Reader" automatically refreshes slides on changes; ] .footnote[[*] Not really. See next page.] --- # Math Expressions You can write LaTeX math expressions inside a pair of dollar signs, e.g. &#36;\alpha+\beta$ renders `\(\alpha+\beta\)`. You can use the display style with double dollar signs: ``` $$\bar{X}=\frac{1}{n}\sum_{i=1}^nX_i$$ ``` `$$\bar{X}=\frac{1}{n}\sum_{i=1}^nX_i$$` Limitations: 1. The source code of a LaTeX math expression must be in one line, unless it is inside a pair of double dollar signs, in which case the starting `$$` must appear in the very beginning of a line, followed immediately by a non-space character, and the ending `$$` must be at the end of a line, led by a non-space character; 1. There should not be spaces after the opening `$` or before the closing `$`. 1. Math does not work on the title slide (see [#61](https://github.com/yihui/xaringan/issues/61) for a workaround). --- # R Code ```r # a boring regression fit = lm(dist ~ 1 + speed, data = cars) coef(summary(fit)) ``` ``` # Estimate Std. Error t value Pr(>|t|) # (Intercept) -17.579095 6.7584402 -2.601058 1.231882e-02 # speed 3.932409 0.4155128 9.463990 1.489836e-12 ``` ```r dojutsu = c('地爆天星', '天照', '加具土命', '神威', '須佐能乎', '無限月読') grep('天', dojutsu, value = TRUE) ``` ``` # [1] "地爆天星" "天照" ``` --- # R Plots ```r par(mar = c(4, 4, 1, .1)) plot(cars, pch = 19, col = 'darkgray', las = 1) abline(fit, lwd = 2) ``` <!-- --> --- # Tables If you want to generate a table, make sure it is in the HTML format (instead of Markdown or other formats), e.g., ```r knitr::kable(head(iris), format = 'html') ``` <table> <thead> <tr> <th style="text-align:right;"> Sepal.Length </th> <th style="text-align:right;"> Sepal.Width </th> <th style="text-align:right;"> Petal.Length </th> <th style="text-align:right;"> Petal.Width </th> <th style="text-align:left;"> Species </th> </tr> </thead> <tbody> <tr> <td style="text-align:right;"> 5.1 </td> <td style="text-align:right;"> 3.5 </td> <td style="text-align:right;"> 1.4 </td> <td style="text-align:right;"> 0.2 </td> <td style="text-align:left;"> setosa </td> </tr> <tr> <td style="text-align:right;"> 4.9 </td> <td style="text-align:right;"> 3.0 </td> <td style="text-align:right;"> 1.4 </td> <td style="text-align:right;"> 0.2 </td> <td style="text-align:left;"> setosa </td> </tr> <tr> <td style="text-align:right;"> 4.7 </td> <td style="text-align:right;"> 3.2 </td> <td style="text-align:right;"> 1.3 </td> <td style="text-align:right;"> 0.2 </td> <td style="text-align:left;"> setosa </td> </tr> <tr> <td style="text-align:right;"> 4.6 </td> <td style="text-align:right;"> 3.1 </td> <td style="text-align:right;"> 1.5 </td> <td style="text-align:right;"> 0.2 </td> <td style="text-align:left;"> setosa </td> </tr> <tr> <td style="text-align:right;"> 5.0 </td> <td style="text-align:right;"> 3.6 </td> <td style="text-align:right;"> 1.4 </td> <td style="text-align:right;"> 0.2 </td> <td style="text-align:left;"> setosa </td> </tr> <tr> <td style="text-align:right;"> 5.4 </td> <td style="text-align:right;"> 3.9 </td> <td style="text-align:right;"> 1.7 </td> <td style="text-align:right;"> 0.4 </td> <td style="text-align:left;"> setosa </td> </tr> </tbody> </table> --- # HTML Widgets I have not thoroughly tested HTML widgets against **xaringan**. Some may work well, and some may not. It is a little tricky. Similarly, the Shiny mode (`runtime: shiny`) does not work. I might get these issues fixed in the future, but these are not of high priority to me. I never turn my presentation into a Shiny app. When I need to demonstrate more complicated examples, I just launch them separately. It is convenient to share slides with other people when they are plain HTML/JS applications. See the next page for two HTML widgets. --- ```r library(leaflet) leaflet() %>% addTiles() %>% setView(-93.65, 42.0285, zoom = 17) ``` <div id="htmlwidget-6e8a70be66e3a8427687" style="width:100%;height:432px;" class="leaflet html-widget"></div> <script type="application/json" data-for="htmlwidget-6e8a70be66e3a8427687">{"x":{"options":{"crs":{"crsClass":"L.CRS.EPSG3857","code":null,"proj4def":null,"projectedBounds":null,"options":{}}},"calls":[{"method":"addTiles","args":["//{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",null,null,{"minZoom":0,"maxZoom":18,"tileSize":256,"subdomains":"abc","errorTileUrl":"","tms":false,"noWrap":false,"zoomOffset":0,"zoomReverse":false,"opacity":1,"zIndex":1,"detectRetina":false,"attribution":"© <a href=\"http://openstreetmap.org\">OpenStreetMap<\/a> contributors, <a href=\"http://creativecommons.org/licenses/by-sa/2.0/\">CC-BY-SA<\/a>"}]}],"setView":[[42.0285,-93.65],17,[]]},"evals":[],"jsHooks":[]}</script> --- ```r DT::datatable( head(iris, 10), fillContainer = FALSE, options = list(pageLength = 8) ) ``` <div id="htmlwidget-a828c8bb9a0fe6d70a6a" style="width:100%;height:auto;" class="datatables html-widget"></div> <script type="application/json" data-for="htmlwidget-a828c8bb9a0fe6d70a6a">{"x":{"filter":"none","fillContainer":false,"data":[["1","2","3","4","5","6","7","8","9","10"],[5.1,4.9,4.7,4.6,5,5.4,4.6,5,4.4,4.9],[3.5,3,3.2,3.1,3.6,3.9,3.4,3.4,2.9,3.1],[1.4,1.4,1.3,1.5,1.4,1.7,1.4,1.5,1.4,1.5],[0.2,0.2,0.2,0.2,0.2,0.4,0.3,0.2,0.2,0.1],["setosa","setosa","setosa","setosa","setosa","setosa","setosa","setosa","setosa","setosa"]],"container":"<table class=\"display\">\n <thead>\n <tr>\n <th> <\/th>\n <th>Sepal.Length<\/th>\n <th>Sepal.Width<\/th>\n <th>Petal.Length<\/th>\n <th>Petal.Width<\/th>\n <th>Species<\/th>\n <\/tr>\n <\/thead>\n<\/table>","options":{"pageLength":8,"columnDefs":[{"className":"dt-right","targets":[1,2,3,4]},{"orderable":false,"targets":0}],"order":[],"autoWidth":false,"orderClasses":false,"lengthMenu":[8,10,25,50,100]}},"evals":[],"jsHooks":[]}</script> --- # Some Tips - Do not forget to try the `yolo` option of `xaringan::moon_reader`. ```yaml output: xaringan::moon_reader: yolo: true ``` --- # Some Tips - Slides can be automatically played if you set the `autoplay` option under `nature`, e.g. go to the next slide every 30 seconds in a lightning talk: ```yaml output: xaringan::moon_reader: nature: autoplay: 30000 ``` - If you want to restart the play after it reaches the last slide, you may set the sub-option `loop` to TRUE, e.g., ```yaml output: xaringan::moon_reader: nature: autoplay: interval: 30000 loop: true ``` --- # Some Tips - A countdown timer can be added to every page of the slides using the `countdown` option under `nature`, e.g. if you want to spend one minute on every page when you give the talk, you can set: ```yaml output: xaringan::moon_reader: nature: countdown: 60000 ``` Then you will see a timer counting down from `01:00`, to `00:59`, `00:58`, ... When the time is out, the timer will continue but the time turns red. --- # Some Tips - The title slide is created automatically by **xaringan**, but it is just another remark.js slide added before your other slides. The title slide is set to `class: center, middle, inverse, title-slide` by default. You can change the classes applied to the title slide with the `titleSlideClass` option of `nature` (`title-slide` is always applied). ```yaml output: xaringan::moon_reader: nature: titleSlideClass: [top, left, inverse] ``` -- - If you'd like to create your own title slide, disable **xaringan**'s title slide with the `seal = FALSE` option of `moon_reader`. ```yaml output: xaringan::moon_reader: seal: false ``` --- # Some Tips - There are several ways to build incremental slides. See [this presentation](https://slides.yihui.org/xaringan/incremental.html) for examples. - The option `highlightLines: true` of `nature` will highlight code lines that start with `*`, or are wrapped in `{{ }}`, or have trailing comments `#<<`; ```yaml output: xaringan::moon_reader: nature: highlightLines: true ``` See examples on the next page. --- # Some Tips .pull-left[ An example using a leading `*`: ```r if (TRUE) { ** message("Very important!") } ``` Output: ```r if (TRUE) { * message("Very important!") } ``` This is invalid R code, so it is a plain fenced code block that is not executed. ] .pull-right[ An example using `{{}}`: ```` ```{r tidy=FALSE} if (TRUE) { *{{ message("Very important!") }} } ``` ```` Output: ```r if (TRUE) { * message("Very important!") } ``` ``` ## Very important! ``` It is valid R code so you can run it. Note that `{{}}` can wrap an R expression of multiple lines. ] --- # Some Tips An example of using the trailing comment `#<<` to highlight lines: ````markdown ```{r tidy=FALSE} library(ggplot2) ggplot(mtcars) + aes(mpg, disp) + geom_point() + #<< geom_smooth() #<< ``` ```` Output: ```r library(ggplot2) ggplot(mtcars) + aes(mpg, disp) + * geom_point() + * geom_smooth() ``` --- # Some Tips When you enable line-highlighting, you can also use the chunk option `highlight.output` to highlight specific lines of the text output from a code chunk. For example, `highlight.output = TRUE` means highlighting all lines, and `highlight.output = c(1, 3)` means highlighting the first and third line. ````md ```{r, highlight.output=c(1, 3)} head(iris) ``` ```` ``` *## Sepal.Length Sepal.Width Petal.Length Petal.Width Species ## 1 5.1 3.5 1.4 0.2 setosa *## 2 4.9 3.0 1.4 0.2 setosa ## 3 4.7 3.2 1.3 0.2 setosa ## 4 4.6 3.1 1.5 0.2 setosa ## 5 5.0 3.6 1.4 0.2 setosa ## 6 5.4 3.9 1.7 0.4 setosa ``` Question: what does `highlight.output = c(TRUE, FALSE)` mean? (Hint: think about R's recycling of vectors) --- # Some Tips - To make slides work offline, you need to download a copy of remark.js in advance, because **xaringan** uses the online version by default (see the help page `?xaringan::moon_reader`). - You can use `xaringan::summon_remark()` to download the latest or a specified version of remark.js. By default, it is downloaded to `libs/remark-latest.min.js`. - Then change the `chakra` option in YAML to point to this file, e.g. ```yaml output: xaringan::moon_reader: chakra: libs/remark-latest.min.js ``` - If you used Google fonts in slides (the default theme uses _Yanone Kaffeesatz_, _Droid Serif_, and _Source Code Pro_), they won't work offline unless you download or install them locally. The Heroku app [google-webfonts-helper](https://google-webfonts-helper.herokuapp.com/fonts) can help you download fonts and generate the necessary CSS. --- # Macros - remark.js [allows users to define custom macros](https://github.com/yihui/xaringan/issues/80) (JS functions) that can be applied to Markdown text using the syntax `![:macroName arg1, arg2, ...]` or ``. For example, before remark.js initializes the slides, you can define a macro named `scale`: ```js remark.macros.scale = function (percentage) { var url = this; return '<img src="' + url + '" style="width: ' + percentage + '" />'; }; ``` Then the Markdown text ```markdown  ``` will be translated to ```html <img src="image.jpg" style="width: 50%" /> ``` --- # Macros (continued) - To insert macros in **xaringan** slides, you can use the option `beforeInit` under the option `nature`, e.g., ```yaml output: xaringan::moon_reader: nature: beforeInit: "macros.js" ``` You save your remark.js macros in the file `macros.js`. - The `beforeInit` option can be used to insert arbitrary JS code before `remark.create()`. Inserting macros is just one of its possible applications. --- # CSS Among all options in `xaringan::moon_reader`, the most challenging but perhaps also the most rewarding one is `css`, because it allows you to customize the appearance of your slides using any CSS rules or hacks you know. You can see the default CSS file [here](https://github.com/yihui/xaringan/blob/master/inst/rmarkdown/templates/xaringan/resources/default.css). You can completely replace it with your own CSS files, or define new rules to override the default. See the help page `?xaringan::moon_reader` for more information. --- # CSS For example, suppose you want to change the font for code from the default "Source Code Pro" to "Ubuntu Mono". You can create a CSS file named, say, `ubuntu-mono.css`: ```css @import url(https://fonts.googleapis.com/css?family=Ubuntu+Mono:400,700,400italic); .remark-code, .remark-inline-code { font-family: 'Ubuntu Mono'; } ``` Then set the `css` option in the YAML metadata: ```yaml output: xaringan::moon_reader: css: ["default", "ubuntu-mono.css"] ``` Here I assume `ubuntu-mono.css` is under the same directory as your Rmd. See [yihui/xaringan#83](https://github.com/yihui/xaringan/issues/83) for an example of using the [Fira Code](https://github.com/tonsky/FiraCode) font, which supports ligatures in program code. --- # CSS (with Sass) **xaringan** also supports Sass support via **rmarkdown**. Suppose you want to use the same color for different elements, e.g., first heading and bold text. You can create a `.scss` file, say `mytheme.scss`, using the [sass](https://sass-lang.com/) syntax with variables: ```scss $mycolor: #ff0000; .remark-slide-content > h1 { color: $mycolor; } .remark-slide-content strong { color: $mycolor; } ``` Then set the `css` option in the YAML metadata using this file placed under the same directory as your Rmd: ```yaml output: xaringan::moon_reader: css: ["default", "mytheme.scss"] ``` This requires **rmarkdown** >= 2.8 and the [**sass**](https://rstudio.github.io/sass/) package. You can learn more about **rmarkdown** and **sass** support in [this blog post](https://blog.rstudio.com/2021/04/15/2021-spring-rmd-news/#sass-and-scss-support-for-html-based-output) and in [**sass** overview vignette](https://rstudio.github.io/sass/articles/sass.html). --- # Themes Don't want to learn CSS? Okay, you can use some user-contributed themes. A theme typically consists of two CSS files `foo.css` and `foo-fonts.css`, where `foo` is the theme name. Below are some existing themes: ```r names(xaringan:::list_css()) ``` ``` ## [1] "chocolate-fonts" "chocolate" "default-fonts" ## [4] "default" "duke-blue" "fc-fonts" ## [7] "fc" "hygge-duke" "hygge" ## [10] "ki-fonts" "ki" "kunoichi" ## [13] "lucy-fonts" "lucy" "metropolis-fonts" ## [16] "metropolis" "middlebury-fonts" "middlebury" ## [19] "nhsr-fonts" "nhsr" "ninjutsu" ## [22] "rladies-fonts" "rladies" "robot-fonts" ## [25] "robot" "rutgers-fonts" "rutgers" ## [28] "shinobi" "tamu-fonts" "tamu" ## [31] "uio-fonts" "uio" "uo-fonts" ## [34] "uo" "uol-fonts" "uol" ## [37] "useR-fonts" "useR" ``` --- # Themes To use a theme, you can specify the `css` option as an array of CSS filenames (without the `.css` extensions), e.g., ```yaml output: xaringan::moon_reader: css: [default, metropolis, metropolis-fonts] ``` If you want to contribute a theme to **xaringan**, please read [this blog post](https://yihui.org/en/2017/10/xaringan-themes). --- class: inverse, middle, center background-image: url(https://upload.wikimedia.org/wikipedia/commons/3/39/Naruto_Shiki_Fujin.svg) background-size: contain # Naruto --- background-image: url(https://upload.wikimedia.org/wikipedia/commons/b/be/Sharingan_triple.svg) background-size: 100px background-position: 90% 8% # Sharingan The R package name **xaringan** was derived¹ from **Sharingan**, a dōjutsu in the Japanese anime _Naruto_ with two abilities: - the "Eye of Insight" - the "Eye of Hypnotism" I think a presentation is basically a way to communicate insights to the audience, and a great presentation may even "hypnotize" the audience.^2,3 .footnote[ [1] In Chinese, the pronounciation of _X_ is _Sh_ /ʃ/ (as in _shrimp_). Now you should have a better idea of how to pronounce my last name _Xie_. [2] By comparison, bad presentations only put the audience to sleep. [3] Personally I find that setting background images for slides is a killer feature of remark.js. It is an effective way to bring visual impact into your presentations. ] --- # Naruto terminology The **xaringan** package borrowed a few terms from Naruto, such as - [Sharingan](https://naruto.fandom.com/wiki/Sharingan) (写輪眼; the package name) - The [moon reader](https://naruto.fandom.com/wiki/Moon_Reader) (月読; an attractive R Markdown output format) - [Chakra](https://naruto.fandom.com/wiki/Chakra) (查克拉; the path to the remark.js library, which is the power to drive the presentation) - [Nature transformation](https://naruto.fandom.com/wiki/Nature_Transformation) (性質変化; transform the chakra by setting different options) - The [infinite moon reader](https://naruto.fandom.com/wiki/Infinite_Tsukuyomi) (無限月読; start a local web server to continuously serve your slides) - The [summoning technique](https://naruto.fandom.com/wiki/Summoning_Technique) (download remark.js from the web) You can click the links to know more about them if you want. The jutsu "Moon Reader" may seem a little evil, but that does not mean your slides are evil. --- class: center # Hand seals (印) Press `h` or `?` to see the possible ninjutsu you can use in remark.js.  --- class: center, middle # Thanks! Slides created via the R package [**xaringan**](https://github.com/yihui/xaringan). The chakra comes from [remark.js](https://remarkjs.com), [**knitr**](https://yihui.org/knitr/), and [R Markdown](https://rmarkdown.rstudio.com).