3.4 单个文档

有时你可能不想写一本书,而是想写一篇长篇文章或报告。通常你要做的是使用特定的输出格式函数调用 rmarkdown::render()。这种情况下缺少的主要功能是图片/表格/方程的自动编号,以及对图片/表格/方程/章节的交叉引用。我们已经将这些特性从 bookdown 中分解出来,这样你就可以使用它们而无需准备一本包含多个 Rmd 文件的书籍。

函数 html_document2()tufte_html2()pdf_document2()word_document2()tufte_handout2()tufte_book2() 就是为此目的而设计的。如果使用这些输出格式渲染一份 R Markdown 文档,例如 bookdown::html_document2,你将能够对图片/表格自动编号,并能够使用第 2 章描述的语法在单个 HTML 页面中对它们进行交叉引用。

下面是单个 Rmd 文件的 YAML 元数据中这些输出格式的几个例子(你也可以把这些格式添加到 _output.yml 文件中)。

output:
  bookdown::html_document2: default
  bookdown::pdf_document2:
    keep_tex: true
  bookdown::word_document2:
    toc: true

上面的 HTML 和 PDF 输出格式函数基本上是对输出格式 bookdown::html_bookbookdown::pdf_book 的封装,其意义在于它们改变了 base_format 参数。例如,你可以查阅 pdf_document2 的源代码。

bookdown::pdf_document2
## function (...) 
## {
##     pdf_book(..., base_format = rmarkdown::pdf_document)
## }
## <bytecode: 0x00000172eb7ffd10>
## <environment: namespace:bookdown>

在你知道这个事实后,你可以通过使用适当的 base_format 将同样的想法应用于其他输出格式。例如,你可以通过使用 YAML 元数据将 bookdown 的功能移植到 rticles 软件包(Allaire, Xie, Dervieux, R Foundation, et al. 2023)中的 jss_article 格式。

output:
  bookdown::pdf_book:
    base_format: rticles::jss_article

然后你就可以使用我们在第 2 章中介绍的所有功能了。

尽管 gitbook() 格式主要是为书籍设计的,但实际上你也可以将其应用于单个 R Markdown 文档。唯一不同的是,在单页输出上不会有搜索按钮,因为你可以简单地使用网络浏览器的搜索工具来查找文本(例如使用 Ctrl + FCommand + F)。你也可以把选项 split_by 设置为 none,这样只会生成一个输出页面,在这种情况下不会有任何导航按钮,因为没有其他页面可以导航。如果你愿意,仍然可以生成多页 HTML 文件。当只生成单一的输出页面时,另一个你可能想使用的配置项是 self_contained = TRUE

参考文献

Allaire, JJ, Yihui Xie, Christophe Dervieux, R Foundation, Hadley Wickham, Journal of Statistical Software, Ramnath Vaidyanathan, et al. 2023. Rticles: Article Formats for r Markdown. https://github.com/rstudio/rticles.