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

1.3 Usage

A typical bookdown book contains multiple chapters, and one chapter lives in one R Markdown file, with the filename extension .Rmd. Each R Markdown file must start immediately with the chapter title using the first-level heading, e.g., # Chapter Title. All R Markdown files must be encoded in UTF-8, especially when they contain multi-byte characters such as Chinese, Japanese, and Korean. Here is an example (the bullets are the filenames, followed by the file content):

一本典型的bookdown包含多个章节，一个章节存在于一个R Markdown文件中，文件扩展名为..Rmd 。每个R Markdown文件必须立即以第一级标题的章节标题开始，例如: # 章节标题。所有R Markdown文件必须用UTF-8编码，特别是当它们包含多字节字符，如中文、日文和韩文时。下面是一个例子(项目符号是文件名，后面跟着文件内容):

  • index.Rmd

    1. # Preface {-}
    2. In this book, we will introduce an interesting
    3. method.

  • 01-intro.Rmd

    1. # Introduction
    2. This chapter is an overview of the methods that
    3. we propose to solve an **important problem**.

  • 02-literature.Rmd

    1. # Literature
    2. Here is a review of existing methods.

  • 03-method.Rmd

    1. # Methods
    2. We describe our methods in this chapter.

  • 04-application.Rmd

    1. # Applications
    2. Some _significant_ applications are demonstrated
    3. in this chapter.
    4. ## Example one
    5. ## Example two

  • 05-summary.Rmd

    1. # Final Words
    2. We have finished a nice book.

    By default, bookdown merges all Rmd files by the order of filenames, e.g., 01-intro.Rmd will appear before 02-literature.Rmd. Filenames that start with an underscore _ are skipped. If there exists an Rmd file named index.Rmd, it will always be treated as the first file when merging all Rmd files. The reason for this special treatment is that the HTML file index.html to be generated from index.Rmd is usually the default index file when you view a website, e.g., you are actually browsing http://yihui.org/index.html when you open http://yihui.org/.

默认情况下，bookdown会按照文件名的顺序合并所有Rmd文件，例如01-intro.Rmd 会出现在02-literature.Rmd之前。以下划线_开头的文件名将被跳过。当合并所有Rmd文件时,如果存在一个名为index.Rmd的Rmd文件,它总是被视为第一个文件。这种特殊处理的原因是HTML文件index.html 是从index.Rmd生成的,当你浏览一个网站时，它通常是默认的索引文件，例如，当你打开http://yihui.org/时，你实际上是在浏览http://yihui.org/index.html。

You can override the above behavior by including a configuration file named _bookdown.yml in the book directory. It is a YAML file (https://en.wikipedia.org/wiki/YAML), and R Markdown users should be familiar with this format since it is also used to write the metadata in the beginning of R Markdown documents (you can learn more about YAML in Section B.2). You can use a field named rmd_files to define your own list and order of Rmd files for the book. For example,

您可以通过在图书目录下配置一个 名为_bookdown.yml 的文件来覆盖上述行为。它是一个YAML文件(https://en.wikipedia.org/wiki/YAML)， R Markdown用户应该熟悉这种格式，因为它也用于在R Markdown文档的开头编写元数据（metadata）(您可以在B.2节中了解更多关于YAML的信息)。您可以使用一个名为rmd_files的字段来定义您自己的列表和该书的Rmd文件的顺序。例如,

  1. rmd_files: ["index.Rmd", "abstract.Rmd", "intro.Rmd"]

In this case, bookdown will use the list of files you defined in this YAML field (index.Rmd will be added to the list if it exists, and filenames starting with underscores are always ignored). If you want both HTML and LaTeX/PDF output from the book, and use different Rmd files for HTML and LaTeX output, you may specify these files for the two output formats separately, e.g.,

在这种情况下，bookdown可以使用您在YAML字段(index)中定义的文件列表。(如果存在index.Rmd,它将被添加到列表中，以下划线开头的文件名会被忽略)。如果你想从书中同时得到HTML和LaTeX/PDF输出，并且为HTML和LaTeX输出使用不同的Rmd文件，你可以为这两种输出格式分别指定这些文件，例如:

  1. rmd_files:
  2.   html: ["index.Rmd", "abstract.Rmd", "intro.Rmd"]
  3.   latex: ["abstract.Rmd", "intro.Rmd"]

Although we have been talking about R Markdown files, the chapter files do not actually have to be R Markdown. They can be plain Markdown files (.md), and do not have to contain R code chunks at all. You can certainly use bookdown to compose novels or poems!

At the moment, the major output formats that you may use include bookdown::pdf_book, bookdown::gitbook, bookdown::html_book, and bookdown::epub_book. There is a bookdown::render_book() function similar to rmarkdown::render(), but it was designed to render multiple Rmd documents into a book using the output format functions. You may either call this function from command line directly, or click the relevant buttons in the RStudio IDE. Here are some command-line examples:

虽然我们一直在讨论R Markdown文件，但章节文件并不一定要是R Markdown。它们可以是普通的Markdown文件(.md),并且根本不需要包含R代码块。你当然可以用bowkdown来写小说或诗歌!
目前，您可能使用的主要输出格式包括 bookdown::pdf_book, bookdown::gitbook, bookdown::html_book, 和bookdown::epub_book。有一个类似于rmarkdown::render()函数的 bookdown::render_book() 函数，但它的设计目的是使用输出格式函数将多个Rmd文档转换成一本书。您可以直接从命令行调用这个函数，或者单击RStudio IDE中的相关按钮。下面是一些命令行示例:

  1. bookdown::render_book("foo.Rmd", "bookdown::gitbook")
  2. bookdown::render_book("foo.Rmd", "bookdown::pdf_book")
  3. bookdown::render_book("foo.Rmd", bookdown::gitbook(lib_dir = "libs"))
  4. bookdown::render_book("foo.Rmd", bookdown::pdf_book(keep_tex = TRUE))

To use render_book and the output format functions in the RStudio IDE, you can define a YAML field named site that takes the value bookdown::bookdown_site,1 and the output format functions can be used in the output field, e.g.,

要使用render_book 和在RStudio IDE的格式输出函数, 你可以定义一个名为 site 的YAML 字段 ，该字段值为bookdown::bookdown_site,1 ，输出格式函数可以在 output 字段中使用，例如,

  1. ---
  2. site: "bookdown::bookdown_site"
  3. output:
  4.   bookdown::gitbook:
  5.     lib_dir: "book_assets"
  6.   bookdown::pdf_book:
  7.     keep_tex: yes
  8. ---

Then you can click the Build Book button in the Build pane in RStudio to compile the Rmd files into a book, or click the Knit button on the toolbar to preview the current chapter.

More bookdown configuration options in _bookdown.yml are explained in Section 4.4. Besides these configurations, you can also specify some Pandoc-related configurations in the YAML metadata of the first Rmd file of the book, such as the title, author, and date of the book, etc. For example:

截止，您可以单击RStudio中Build 窗格中的Build Book 按钮，将Rmd文件编译为一本书，或者单击工具栏上的 Knit 按钮来预览当前章节。
_bookdown.yml 中的更多bookdown配置选项，详见第 4.4.。除了这些配置之外，您还可以在该书的第一个Rmd文件的YAML元数据（metadata）中指定一些与pandoc相关的配置，例如书名、作者和日期等。例如:

  1. --- 
  2. title: "Authoring A Book with R Markdown"
  3. author: "Yihui Xie"
  4. date: "`r Sys.Date()`"
  5. site: "bookdown::bookdown_site"
  6. output:
  7.   bookdown::gitbook: default
  8. documentclass: book
  9. bibliography: ["book.bib", "packages.bib"]
  10. biblio-style: apalike
  11. link-citations: yes
  12. ---
  1. This function calls bookdown::render_book().↩︎