5.1 Build the book

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")

The most important argument is output_format, which can take a character string of the output format (e.g., 'bookdown::gitbook'). You can leave this argument empty, and the default output format will be the first output format specified in the YAML metadata of the first Rmd file or a separate YAML file _output.yml, as mentioned in Section 4.4. If you plan to generate multiple output formats for a book, you are recommended to specify all formats in _output.yml.

Once all formats are specified in _output.yml, it is easy to write an R or Shell script or Makefile to compile the book. Below is a simple example of using a Shell script to compile a book to HTML (with the GitBook style) and PDF:

#!/usr/bin/env Rscript

bookdown::render_book("index.Rmd", "bookdown::gitbook")
bookdown::render_book("index.Rmd", "bookdown::pdf_book")

The Shell script does not work on Windows (not strictly true, though), but hopefully you get the idea.

The argument ... is passed to the output format function. Arguments clean and envir are passed to rmarkdown::render(), to decide whether to clean up the intermediate files, and specify the environment to evaluate R code, respectively.

The output directory of the book can be specified via the output_dir argument. By default, the book is generated to the _book directory. This can also be changed via the output_dir field in the configuration file _bookdown.yml, so that you do not have to specify it multiple times for rendering a book to multiple output formats. The new_session argument has been explained in Section 1.4. 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.

A number of output files will be generated by render_book(). Sometimes you may want to clean up the book directory and start all over again, e.g., remove the figure and cache files that were generated automatically from knitr. The function clean_book() was designed for this purpose. By default, it tells you which output files you can possibly delete. If you have looked at this list of files, and are sure no files were mistakenly identified as output files (you certainly do not want to delete an input file that you created by hand), you can delete all of them using bookdown::clean_book(TRUE). Since deleting files is a relatively dangerous operation, we would recommend that you maintain your book through version control tools such as GIT, or a service that supports backup and restoration, so you will not lose certain files forever if you delete them by mistake.