13.3 Bookdown包的编排技巧
个人独自创建一个完整的Bookdown文件较为复杂,为方便各类用户的使用,Bookdown作者在开发完成Bookdown包的同时,还提供了相匹配的英文和中文模板,用户可以直接在模板基础上进一步编排,以完成长文档编排任务。
在上一节配置好的Bookdown使用环境的基础上,用户可以根据自己需要,选择下载英文模板(https://github.com/rstudio/bookdown-demo)或中文模板(https://github.com/yihui/bookdown-chinese)文件到本地并解压。在解压缩后得到的文件目录里找到扩展名为Rproj的文件,默认用RStudio将其打开,在RStudio的右上面板依次单击Build标签、build book,模板书将出现在名为_book的子文件夹里,若模板书输出成功,则说明Bookdown的使用环境配置成功。
在RStudio的右下面板里,有一些扩展名为Rmd的文件,逐个打开这些文件,将其中的内容修改成自己期望的内容。值得注意的是,除了index.Rmd文件外,可以手动删除不需要的Rmd文件。Rmd文件的编排可以参照如下步骤展开。
首先,在RStudio中打开index.Rmd文件,可以看到的是,YAML文件头包含Pandoc文件格式转换需要的元数据,如标题、作者、日期等,如图13-2所示。
图13-2 index.Rmd文件的YAML文件头示例
一个典型的Bookdown文档包含多个章节,每一个章节以单个Rmd文件存在。除了index.Rmd文件之外,正文部分的Rmd文件一般以“01-name,02-name,…”的方式命名,如果文件名需要添加作者信息,可以使用“00-auther”的方式命名,Bookdown会默认按照文件名的顺序合并Rmd文件。此外,章节的顺序也可通过在_bookdown.yml文件中设置参数rmd_files:[“file1.Rmd”,“file2.Rmd”,…]实现。
其次,在对Rmd文件进行编辑时,必须以“＃章节标题”开头,同时尽量为每一个章节标题添加一个标签,以方便交叉引用。添加标签的方式为:在标题后面添加{＃label},且标签名称必须为英文,不得出现“_”符号,标签与标题之间用空格隔开,示例如下。
上述示例设置的是一级目录,如果要设置二级或更深层级目录,可以通过增加“＃”的方式实现。
如果用户撰写的长文档或图书需要自动生成目录,可以在第一个包含正文内容的Rmd文件的第一行(标题之前)添加mainmatter,指明此处是正文内容的开始。
通常index.Rmd文件里也需要有一个章节的内容,如果不需要对这一章节编号,可以写成“＃前言{-}”的形式,其中{-}代表不对此标题进行编号。如果文章内容较长,可以使用“＃(PART)name{-}”对文章进行分节,这种方式常用于图书的编排。“＃(PART)name{-}”的使用示例如图13-3所示。
图13-3 ＃(PART)name{-}的使用示例
考虑到Bookdown包输出的文档类型较为复杂,涉及La Tex、YAML、css以及Markdown等标记语言格式的转换,建议初学者在下载的英文或中文模板基础上撰写长文档或书籍,避免因不熟悉而造成编译出错,待熟练掌握较多知识后,再尝试编辑自定义模板。