Setup, tips and tricks


Labels, citations and references


Chapters and sections can be labeled using {#label} after the name.
We can reference Chapter ?? by writing @ ref(intro).


Parenthetical citation can be created by writing [@xie2015], e.g. (Xie 2015, 45)
Narrative citations can be created by writing @R-bookdown, e.g. Xie (2021)


Figures and tables with captions will be placed in figure and table environments, respectively.

Figures can be referenced by its code chunk label with the fig: prefix, e.g., see Figure 0.1

Here is a nice figure!

Figure 0.1: Here is a nice figure!

Tables can likewise be referenced by its code chunk label with the tab: prefix, e.g., see Table 0.1

Table 0.1: Here is a nice table!
Sepal.Length Sepal.Width Petal.Length Petal.Width Species
5.1 3.5 1.4 0.2 setosa
4.9 3.0 1.4 0.2 setosa
4.7 3.2 1.3 0.2 setosa

Caching results

First option:
The chunk option cache = TRUE can be set to TRUE if a code chunk is time-consuming to run. When the cache is turned on, knitr will skip the execution of this code chunk if it has been executed before and nothing in the code chunk has changed since then. If the code chunk is modified (e.g., revise the code or the chunk options), the previous cache will be automatically invalidated, and knitr will cache the chunk again.

```{r import-data, cache=TRUE}
d <- read.csv('my-precious.csv')

Second option:
The function xfun::cache_rds() evaluates the expression inside it’s parameter and saves the result to a .rds file; the next time you run cache_rds() again, it reads the .rds file and returns the result immediately without evaluating the expression again.

# write your time-consuming code in this expression 

When xfun::cache_rds() is called inside a code chunk, the path of the .rds file will be stored in an automatically generated cache folder.

Third option:  Manual caching is also an option, however, in this case, the only (and also simple) way to invalidate the cache and make it run the code block again is to delete the .rds file

if (file.exists('results.rds')) {
  res = readRDS('results.rds')
} else {
  res = compute_it()  # a time-consuming function
  saveRDS(res, 'results.rds')

Hot loading bookdown

Instead of running render_book() or preview_chapter() over and over again, you can use Hot loading to get a live preview of the book in the web browser. Hot reloading only refreshes the files that were changed without rebuilding the whole book, so the only thing you need to do is save the Rmd file. The function serve_book() in bookdown can start a local web server to serve the HTML output based on the servr package. Reference link

serve_book(dir = ".", output_dir = "_book", preview = TRUE, 
           in_session = TRUE, quiet = FALSE, …)

Extra resources

R markdown Reference guide with Markdown Syntax can be found here Link

BibTeX reference bibliography can be found here Link


Xie, Yihui. 2015. Dynamic Documents with R and Knitr. 2nd ed. Boca Raton, Florida: Chapman; Hall/CRC.
———. 2021. Bookdown: Authoring Books and Technical Documents with r Markdown.