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

3.4 A single document

3.4 单个文档

Sometimes you may not want to write a book, but a single long-form article or report instead. Usually what you do is call rmarkdown::render() with a certain output format. The main features missing there are the automatic numbering of figures/tables/equations, and cross-referencing figures/tables/equations/sections. We have factored out these features from bookdown, so that you can use them without having to prepare a book of multiple Rmd files.

The functions html_document2(), tufte_html2(), pdf_document2(), word_document2(), tufte_handout2(), and tufte_book2() are designed for this purpose. If you render an R Markdown document with the output format, say, bookdown::html_document2, you will get figure/table numbers and be able to cross-reference them in the single HTML page using the syntax described in Chapter 2.

Below are a few examples of these output formats in the YAML metadata of a single Rmd file (you can also add these formats to the _output.yml file):

有时你可能不想写一本书，而是想写一篇长篇文章或报告。通常你要做的是使用一个特定的输出格式调用 rmarkdown::render() . 它缺少的主要功能是：为igures/tables/equations自动编号 ，以及figures/tables/equations/sections的交叉引用. 我们已经将这些特性从bookdown中分离出来，这样您就可以使用它们，而不必准备一本包含多个Rmd文件的书。
函数 html_document2(), tufte_html2(), pdf_document2(), word_document2(), tufte_handout2(), 和tufte_book2() 就是出于这个目的设计的. 如果你想要将R Markdown文档 输出为特定格式, 可以调用, bookdown::html_document2,你将获得 figure/table编号，而且它可以在单个的html中交叉引用，具体使用见第2章中的描述.
Below are a few examples of these output formats in the YAML metadata of a single Rmd file (you can also add these formats to the _output.yml file):
下面是单个Rmd文件的YAML元数据中的这些输出格式的几个示例(您也可以将这些格式添加到 _output.yml文件):

  1. output:
  2.   bookdown::html_document2: default
  3.   bookdown::pdf_document2:
  4.     keep_tex: true
  5.   bookdown::word_document2:
  6.     toc: true

The above HTML and PDF output format functions are basically wrappers of output formats bookdown::html_book and bookdown::pdf_book, in the sense that they changed the base_format argument. For example, you can take a look at the source code of pdf_document2:

上面的HTML和PDF输出格式函数基本上是bookdown::html_book and bookdown::pdf_book的封装器，`因为他们改变了base_format参数. 例如， 你可以查看pdf_document2`源码:

  1. bookdown::pdf_document2
  1. ## function (...) 
  2. ## {
  3. ##     pdf_book(..., base_format = rmarkdown::pdf_document)
  4. ## }
  5. ## <bytecode: 0x7f9f016811c8>
  6. ## <environment: namespace:bookdown>

After you know this fact, you can apply the same idea to other output formats by using the appropriate base_format. For example, you can port the bookdown features to the jss_article format in the rticles package (Allaire, Xie, R Foundation, et al. 2021) by using the YAML metadata:

了解了这个事实之后，可以通过使用base_format将同样的思想应用到其他输出格式上。例如，您可以通过使用YAML元数据将书签功能移植到rticles 包(Allaire, Xie, R Foundation等人2021年)中的jss_article 格式:

  1. output:
  2.   bookdown::pdf_book:
  3.     base_format: rticles::jss_article

Then you will be able to use all features we introduced in Chapter 2.

接着，你可以使用我们在第2章介绍的所有功能。

Although the gitbook() format was designed primarily for books, you can actually also apply it to a single R Markdown document. The only difference is that there will be no search button on the single page output, because you can simply use the searching tool of your web browser to find text (e.g., press Ctrl + F or Command + F). You may also want to set the option split_by to none to only generate a single output page, in which case there will not be any navigation buttons, since there are no other pages to navigate to. You can still generate multiple-page HTML files if you like. Another option you may want to use is self_contained = TRUE when it is only a single output page.

虽然 gitbook() 格式主要是为书籍设计的，但实际上也可以将其应用于单个R Markdown文档中。唯一的区别是，在单页输出中没有搜索按钮，因为你可以简单地使用浏览器的搜索工具来查找文本(例如., press Ctrl + F or Command + F). 您可能还希望将split_by 选项设置为 none ，用于只生成单个输出页面。在这种情况下，将不存在任何导航按钮，因为没有其他页面可以导航。如果愿意，您仍然可以生成多页HTML文件。当它只是一个输出页面时，您可以使用的另一个选项是self_contained = TRUE 。

References

Allaire, JJ, Yihui Xie, R Foundation, Hadley Wickham, Journal of Statistical Software, Ramnath Vaidyanathan, Association for Computing Machinery, et al. 2021. Rticles: Article Formats for R Markdown. https://github.com/rstudio/rticles.