[BOOKDOWN fourth] editing

1. build

To build all Rmd files into a book, you can call the render_book() function in bookdown. Below are the arguments of render_book():

render_book(input = ".", output_format = NULL, ..., clean = TRUE,
  envir = parent.frame(), clean_envir = !interactive(),
  output_dir = NULL, new_session = NA, preview = FALSE,
  config_file = "_bookdown.yml")

When you set preview = TRUE, only the Rmd files specified in the input argument are rendered, which can be convenient when previewing a certain chapter, since you do not recompile the whole book, but when publishing a book, this argument should certainly be set to FALSE.

2. preview

Building the whole book can be slow when the size of the book is big. Two things can affect the speed of building a book: the computation in R code chunks, and the conversion from Markdown to other formats via Pandoc. The former can be improved by enabling caching in knitr using the chunk option cache = TRUE, and there is not much you can do to make the latter faster. However, you can choose to render only one chapter at a time using the function preview_chapter() in bookdown, and usually this will be much faster than rendering the whole book. Only the Rmd files passed to preview_chapter() will be rendered.

3. serve

Instead of running render_book() or preview_chapter() over and over again, you can actually live preview the book in the web browser, and 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 (Xie 2023c).

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

You pass the root directory of the book to the dir argument, and this function will start a local web server so you can view the book output using the server. The default URL to access the book output is http://127.0.0.1:4321. If you run this function in an interactive R session, this URL will be automatically opened in your web browser. If you are in the RStudio IDE, the RStudio Viewer will be used as the default web browser, so you will be able to write the Rmd source files and preview the output in the same environment (e.g., source on the left and output on the right).

The server will listen to changes in the book root directory: whenever you modify any files in the book directory, serve_book() can detect the changes, recompile the Rmd files, and refresh the web browser automatically. If the modified files do not include Rmd files, it just refreshes the browser (e.g., if you only updated a certain CSS file). This means once the server is launched, all you have to do next is simply write the book and save the files. Compilation and preview will take place automatically as you save files.

If it does not really take too much time to recompile the whole book, you may set the argument preview = FALSE, so that every time you update the book, the whole book is recompiled, otherwise only the modified chapters are recompiled via preview_chapter().

4. IDE

When you click the Knit button to compile an R Markdown document in the RStudio IDE, the default function called by RStudio is rmarkdown::render(), which is not what we want for books. To call the function bookdown::render_book() instead, you can set the site field to be bookdown::bookdown_site in the YAML metadata of the R Markdown document index.Rmd, e.g.,

---
title: "A Nice Book"
site: bookdown::bookdown_site
output:
  bookdown::gitbook: default
---

When you have set site: bookdown::bookdown_site in index.Rmd, RStudio will be able to discover the directory as a book source directory,[¹²]and you will see a button Build Book in the Build pane. You can click the button to build the whole book in different formats, and if you click the Knit button on the toolbar, RStudio will automatically preview the current chapter, and you do not need to use preview_chapter() explicitly.

The bookdown package comes with a few addins for RStudio. If you are not familiar with RStudio addins, you may check out the documentation at http://rstudio.github.io/rstudioaddins/. After you have installed the bookdown package and use RStudio v0.99.878 or later, you will see a dropdown menu on the toolbar named “Addins” and menu items like “Preview Book” and “Input LaTeX Math” after you open the menu.

The addin “Preview Book” calls bookdown::serve_book() to compile and serve the book. It will block your current R session. To avoid blocking the R session, you can daemonize the server using bookdown::serve_book(daemon = TRUE). Note that this addin must be used when the current document opened in RStudio is under the root directory of your book, otherwise serve_book() may not be able to find the book source.

The addin “Input LaTeX Math” is essentially a small Shiny application that provides a text box to help you type LaTeX math expressions. As you type, you will see the preview of the math expression and its LaTeX source code. This will make it much less error-prone to type math expressions — when you type a long LaTeX math expression without preview, it is easy to make mistakes such as X_ij when you meant X_{ij}, or omitting a closing bracket. If you have selected a LaTeX math expression in the RStudio editor before clicking the addin, the expression will be automatically loaded and rendered in the text box. This addin was built on top of the MathQuill library (http://mathquill.com). It is not meant to provide full support to all LaTeX commands for math expressions, but should help you type some common math expressions.

There are also other R packages that provide addins to help you author books. The citr package (Aust 2019) provides an addin named “Insert citations”, which makes it easy to insert citations into R Markdown documents. It scans your bibliography databases, and shows all citation items in a drop-down menu, so you can choose from the list without remembering which citation key corresponds to which citation item.