R沟通｜Bookdown中文书稿写作手册（中）

本教程来自华东师范大学汤银才教授，本人已授权。为了获得更好的阅读体验，可在文末直达原文网站。

第 2 章 bookdown速览

这是第 2 章的内容，概要性地讲解基于bookdown拓展包进行图书排版的整体思路与实现方式.

2.1 关于bookdown

bookdown扩展包 (https://github.com/rstudio/bookdown) 是继knitr和rmarkdown扩展包之后， 另一个增强markdown格式的扩展， 使得Rmd格式可以支持公式、定理、图表、文献自动编号和引用等适用于编写书籍的功能。在bookdown的管理下一本书的内容可以按章节分解成多个Rmd文件， 其中可以包含可执行的R代码， R代码生成的统计汇总结果、表格、图形可以自动插入到生成的内容中， 表格和图形可以是浮动排版的。书的输出格式包括支持gitbook格式的网页图书， 也可以经 LATEX 编译器转换的PDF图书，还可以生成ePub等格式的电子书。建议使用RStudio集成环境来编辑、管理和生成这样的图书，可通过其内建的一键式编译整本书的插件(build)实现。

2.2 快速排版的思路

由rmarkdown完成整个书稿的写作;

由_output.yml完成不同形式呈现的书稿的设计，其中bookdown::gitbook负责html形式的gitbook, bookdown::pdf_book 负责pdf形式的电子书（由 TEXTEX 支持)；bookdown::epub_book负责epub电子书. 部分针对书稿简单设置可放在index.Rmd文件的yml头部(具体放在前面两组三个短线---之间);

书稿按章节进行拆分，借助js支持的html快速生成书稿的初稿，最后再进行整合，根据需要通过Build插件完成gitbook, pdf_book, epub的构建;

借助mathjax处理数学公式的渲染;

尽快可通过联网由cdn上的mathjax.js进行渲染，但速度随因公式的增加，渲染变得很慢，甚至出错。mathjax的本地化是提速的主要解决方案.

重点做好章节、数学公式、表格、图形、定理、文献等浮动对象的处理，在编写过程中及时做好标签设定与引用，见2.6节的汇总表格及后续各章的介绍与示例.

2.3 书的基本设置

一本用bookdown管理的书， 一般放置在某个子目录下，并作为一个RStudio项目(project)用RStudio管理。该目录中的所有的文本文件都要使用UTF-8编码。

2.3.1 index.Rmd文件

一本bookdown书， 一般都需要有一个index.Rmd文件， 这是最后生成的网站的主页的原始文件. 这个文件的开始是YAML元数据部分, 进行全书的有关设置，包括标题、作者、日期及影响全书的一些选项等，放在三个减号组成的两行之间。然后写一些这本书的说明，如书的前言部分。index.Rmd中YAML元数据部分的一个例子如下：

title: "bookdown书稿模板" author: "汤银才" date: "2021-07-25" documentclass: book bibliography: [myrefs.bib] biblio-style: apa link-citations: yes site: bookdown::bookdown_site description: "bookdown写书体验非常好."

注意:

site选项很重要， 一定要有， site: bookdown::bookdown_site使得RStudio能辨认这是一个bookdown图书项目， 从而为其生成一键编译的build快捷方式；

在bookdown项目中与index.Rmd同级的所有.Rmd文件都自动作为书的一章，其好处是作者可以任意地增删章节，编译整本书时将按照文件名的字典序依次进行。实际上， 也可以在_output.yml文件中设置一项rmd_files， 列出所有需要作为一章的文件，并以列出次序编译；

在index.Rmd的元数据中也可以指定一些 LATEX 的选项, 例如

fontsize: 12pt indent: true linestretch: 2.0 link-citations: yes colorlinks: yes lot: true lof: true geometry: - a4paper - tmargin=2.5cm - bmargin=2.5cm - lmargin=3.5cm - rmargin=2.5cm

2.3.2 _bookdown.yml文件

一个bookdown图书项目除了index.Rmd文件之外，还有一些设置文件从index.Rmd文件的元数据部分抽离出来。一个是_bookdown.yml文件, 它存放与整本书的处理有关的YAML元数据。例如

book_filename: "bookdown-template" new_session: yes language:label:fig: "图 "tab: "表 "thm: '定理'def: '定义'exm: '例'proof: '证明: 'ui:chapter_name: ["第 ", " 章"]

其中new_session: true设置很重要，这使得每一个Rmd文件中的R程序都在一个单独的R会话中独立地运行，避免了不同Rmd文件之间同名变量和同名标签的互相干扰。book_filename是最终生成的PDF图书或者ePub电子书的主文件名。language下可以定制一些与章节名、定理名等有关的名称。

2.3.3 _output.yml文件

另一个设置文件是_output.yml， 用于图书输出格式的设置, 本小册子的_output.yml文件内容如下

bookdown::gitbook:css: css/style.csssplit_by: chapterincludes:in_header: _header.htmlconfig:toc:collapse: subpscroll_highlight: yesbefore: |<li><a href="./">bookdown排版模板</a></li>after: |<li><a href="https://bookdown.org" target="blank">本书由 bookdown 强力驱动</a></li>download: [pdf, epub]edit: https://github.com/yihui/bookdown-chinese/edit/master/%ssharing:github: yesfacebook: nopandoc_args: [ "--csl", "apa-6th-edition-no-ampersand.csl" ] bookdown::pdf_book:includes:in_header: latex/preamble.texbefore_body: latex/before_body.texafter_body: latex/after_body.texkeep_tex: yesdev: "cairo_pdf"latex_engine: xelatexcitation_package: biblatextemplate: latex/template.textoc_depth: 3toc_unnumbered: notoc_appendix: yesquote_footer: ["\\begin{flushright}", "\\end{flushright}"]pandoc_args: [ "--top-level-division=chapter" ] bookdown::epub_book:stylesheet: css/style.csspandoc_args: [ "--csl", "apa-6th-edition-no-ampersand.csl" ]

它分别对gitbook、pdf_book和epub_book三种输出格式设置了一些输出选项。其中一些选项是通过文件形式给出设置的，我们再补充说明一下。

style.css是自定义的 CSS 显示格式，在gitbook和epub_book中使用;

_header.html是插入了一部分个性化的HTML代码，其内容将出现在每个生成的HTML文件的head部分。我们在此文件中给出了使用本地的Mathjax实现数学公式离线显示的设置，内容为

<script type="text/x-mathjax-config"> MathJax.Hub.Config({jax: ["input/TeX","output/SVG"],extensions: ["tex2jax.js","MathMenu.js","MathZoom.js"],TeX: {Macros: {bm: ["{\\boldsymbol #1}",1],},extensions: ["AMSmath.js","AMSsymbols.js","noErrors.js","noUndefined.js"]} });</script> <script type="text/javascript"src="http://127.0.0.1/MathJax/MathJax.js"> </script>

其中http://127.0.0.1/MathJax/是本地服务器上Mathjax的位置。

3.apa-6th-edition-no-ampersand.csl 是gitbook和epub_book处理文献使用的风格文件;

4.preamble.tex是处理(编译)bookdown文件经pandoc转化生成的tex文件时导言区需要额外的宏包和设置;

5. before_body.tex 是tex书稿类正文前面的设置，最基本的是

 \frontmatter

6. after_body.tex 是tex书稿类正文之后的设置，最基本的是

\backmatter 7. `template.tex` 是针对`bookdown`编译经`pandoc`转化生成的`tex`文件时的模板，由它生成供`latex_engine`指定的编译方式(`xelatex`)编译的`tex`文件. `index.Rmd`及`_output.yml`中的设置会嵌入到这个模板中，生成完整的单文档`tex`源文件.

其他选项说明：

split_by: chapter: 按章分割书稿；

collapse: subp: 目录中隐藏子节(仅显示二级标题)；

scroll_highlight: yes: 目录滚动时高亮显示，便于定位；

keep_tex: yes: 保留中间生成的tex源文件，便于查错；

dev: "cairo_pdf": 使用cairo_pdf()生成 LATEX 编译需要的图片文件;

latex_engine: xelatex: TeX文件的排版引擎为 XeLATEX, 针对UTF-8编码;

citation_package: biblatex: 文献引用库指定为biblatex, 另一个为natbib;

toc_depth: 3: 目录提取至三级标题;

toc_unnumbered: no: 指定目录编号;

toc_appendix: yes: 附录添加到目录中.

2.4 章节结构

如前所述, 除了index.Rmd文件， 项目中每个.Rmd文件都作为一章，其第一行是以一个#号和空格开头的一级标题。

每一章可以有若干节与子节，分别用markdown的二级标题(二个#开始)和三级标题(三个#开始)编写。bookdown的章、节、子节标题单独成一行，其后可以添加标签, 章节的标签是标题后加空格，然后是大括号内以#号开头的标签， 如

# 引言 {#intro}## 关于bookdown {#bookdown}

bookdown中有二个特殊的标题：

1. 部分

内容相近的章节可以作为一个“部分”。为此，在一个部分的第一个章节文件的章标题前面增加一行， 以# (PART) 开头， 以{-}结尾，例如

   # (PART) bookdown中的浮动对象 {-}

2. 附录

一本书的最后可以有附录， 附录的章节将显示为A.1, B.1这样的格式。为此， 在附录章节的第一个文件开头加如下的第一行标题行：

   # (APPENDIX) 附录 {-}# biblatex介绍 {#biber}

2.5 书的编译

在index.Rmd或者_bookdown.yml中设置site: bookdown::bookdown_site后， RStudio就能识别这个项目是一个bookdown项目， 这时RStudio会有一个Build按钮，其中有Build book快捷图标， 从下拉菜单中选择一个输出格式（包括gitbook、pdf_book、epub_book）， 就可以编译整本书(见下图)。

R Bookdown编译界面.

经build编译生成的图书默认保存在_book子目录中。

对gitbook格式(即HTML网页格式)， 编译完成后会弹出一个预览窗口， 点击“Show in new window”按钮可以将内容在操作系统默认的网络浏览器中打开。我们也可以用其他浏览器(建议使用 Google chrome 浏览器)打开_book子目录中的index.html文件来查看gitbook格式的图书。

对于pdf_book格式，如果成功编译(#fn4 "4")， 也会弹出一个PDF预览窗口。可以在_book子目录中找到这个PDF文件。

对于epub_book格式，如果成功编译，会在操作系统默认的ePub软件(如苹果电脑的book)中打开,并在_book子目录中找到这个ePub文件。

2.6 浮动对象标签与引用汇总

浮动对象标签设置引用格式

标题	(# label)	\@ref(label)
公式	(\#eq:label)	\@ref(eq:label)
图形	label="label"	\@ref(fig:label)
表格	label="label"	\@ref(tab:label)
定理	label="label"	\@ref(prefix:label)
文本	(ref:label)	(ref:label)
文献	biblabel	@biblabel

注：

定理泛指定理类，包括定理(thm)、引理(lem)、推论(cor)、命题(prp)、设想(cnj)、定义(def)、例子(exm)、习题(exr)等, 其中括号中是引用时的前缀(prefix);

文本标签在单独一行中设定，可用在表格与图形的caption中引用，即在 fig.caption, tab.caption选项的设置中引用；

定理类环境标签前缀的汉化可在_bookdown.yml中通过language进行，例如

language:label:fig: "图 "tab: "表 "thm: '定理'def: '定义'exm: '例'

往期精品(点击图片直达文字对应教程)

机器学习

后台回复“生信宝典福利第一波”或点击阅读原文获取教程合集

总结

以上是生活随笔为你收集整理的R沟通｜Bookdown中文书稿写作手册（中）的全部内容，希望文章能够帮你解决所遇到的问题。

如果觉得生活随笔网站内容还不错，欢迎将生活随笔推荐给好友。