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(input, output_format = NULL, ..., clean = TRUE, envir = parent.frame(), clean_envir = !interactive(), output_dir = NULL, new_session = NA, preview = FALSE, encoding = "UTF-8", 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
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.
... is passed to the output format function. Arguments
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
When you render the book to multiple formats in the same R session, you need to be careful because the next format may have access to R objects created from the previous format. You are recommended to render the book with a clean environment for each output format. The argument
clean_envir can be used to clean all objects in the environment specified by
envir. By default, it is
TRUE for non-interactive R sessions (e.g., in batch mode). Note that even
clean_envir = TRUE does not really guarantee the R session is clean. For example, packages loaded when rendering the previous format will remain in the session for the next output format. To make sure each format is rendered in a completely clean R session, you have to actually launch a new R session to build each format, e.g., use the command line
Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::gitbook')" Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::pdf_book')"
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.