作者：Yihui Xie
译者：郑宝童
日期：2021.06.15

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():
你可以调用bookdown中的render_book()函数将所有Rmd文件构建成一本书。下面是render_book()的参数:

  1. render_book(input = ".", output_format = NULL, ..., clean = TRUE, 
  2.   envir = parent.frame(), clean_envir = !interactive(), 
  3.   output_dir = NULL, new_session = NA, preview = FALSE, 
  4.   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.

最重要的参数是output_format，它可以接受输出格式的字符串(例如'bookdown::gitbook')。您可以将此参数设置为空，默认输出格式将是第一个Rmd文件的YAML元数据或单独的YAML文件_output.yml中指定的第一个输出格式, 如第4.4节所述。如果您计划为一本书生成多种输出格式，建议您在_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:

一旦在_output.yml中指定了所有格式, 就很容易编写R或Shell脚本或Makefile来编译这本书。下面是一个使用Shell脚本将一本书编译为HTML(带有GitBook风格)和PDF的简单示例:

  1. #!/usr/bin/env Rscript
  2. bookdown::render_book("index.Rmd", "bookdown::gitbook")
  3. 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.

Shell脚本不能在Windows上工作(这句话不是不是严格意义上的正确)，但是希望您能理解它的意思。

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.

参数 ... 传递给输出格式函数。参数 clean 和 envir 传递给rmarkdown::render() ，以决定是否清理中间文件，并分别指定评估 R代码的环境。

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.

书的输出目录可以通过 output_dir 参数指定。默认情况下，书生成到_book 目录。这也可以通过配置文件 _bookdown.yml 中的 output_dir字段更改，这样你就不必多次指定它来将一本书渲染为多种输出格式。 new_session 参数已在第1.4节中解释。当你设置 preview = TRUE 时，只有在input参数被渲染，这在预览某一章时会很方便，因为你不需要重新编译整本书，但是在出版一本书时，这个参数肯定应该设置为 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.

render_book()将生成多种输出文件。有时您可能想清理 book 目录并重新开始输出文件，例如，删除从 knitr 自动生成的图形和缓存文件。函数 clean_book() 专为此目的而设计。默认情况下，它会告诉您可以删除哪些输出文件。如果您查看了此文件列表，并且确定没有文件被错误地识别为输出文件（您肯定不想删除手动创建的输入文件），您可以使用bookdown::clean_book(TRUE) 删除。由于删除文件是一个比较危险的操作，我们建议您通过GIT等版本控制工具或者支持备份恢复的服务来维护您的书，这样如果您误删除了某些文件，您就不会永远丢失它们。