8 Bookdown

8.1 简介

R的bookdown扩展包(https://github.com/rstudio/bookdown) 是继knitr和rmarkdown扩展包之后， 另一个增强markdown格式的扩展， 使得Rmd格式可以支持公式、定理、图表自动编号和引用、链接， 文献引用和链接等适用于编写书籍的功能。 在bookdown的管理下一本书的内容可以分解成多个Rmd文件， 其中可以有可执行的R代码， R代码生成的文字结果、表格、图形可以自动插入到生成的内容中， 表格和图形可以是浮动排版的。 输出格式主要支持gitbook格式的网页图书， 这种图书在左侧显示目录， 右侧显示内容， 并可以自动链接到上一章和下一章； 通过单独安装的LaTeX编译器支持将书籍转换为一个PDF文件， 支持中文； 可以生成ePub等格式的电子书。

主要用于编写有多个章节的书籍， 也可以用来生成单一文件的研究报告。

建议使用RStudio集成环境制作这样的图书， 该软件内建了一键编译整本书的功能。 需要安装bookdown扩展包的最新版本。 bookdown扩展包现在还比较新， 还有一些BUG， 所以尽可能使用最新版的bookdown扩展包并且及时更新RStudio软件。 查看编译的网站建议使用Google Chrome浏览器， 此浏览器对gitbook的支持较好。

“bookdown: Authoring Books and Technical Documents with R Markdown” (https://bookdown.org/yihui/bookdown/)

因为中文需要一些特殊的设置， 以及在网络条件不好的条件下支持数学公式显示， 北京大学的李东风提供了一个中文书bookdown模板， 下载链接为:https://www.math.pku.edu.cn/teachers/lidf/docs/Rbook/html/_Rbook/bookdown-template-v0-5.zip。此外还有黄湘云的提供的ElegantBookdownhttps://github.com/XiangyunHuang/ElegantBookdown。本书采用的是李东风的模板制作。

8.2 创建图书

可以安装CRAN版或GitHub development版

# install from CRAN
install.packages('bookdown')
# or GitHub
devtools::install_github('rstudio/bookdown')

在RStudio中，可以在菜单栏中点击 File -> New Project -> New Directory -> Book Project using bookdown，即可创建bookdown，然后在RStudio中点击build按钮，将编译图书并在RStudio Viewer中显示HTML版本。图 8.1.

bookdon模板的HTML输出

图8.1: bookdon模板的HTML输出

8.3 编辑图书（Editing）

8.3.1 构建图书（Build the book）

要将所有Rmd文件构建为一个book，可以调用bookdown::render_book()函数。它使用_output.yml(如果存在)中指定的设置。如果在其中指定了多个输出格式，则将构建所有格式。如果您使用的是RStudio，这可以通过Build选项卡完成。如果您只想构建一种格式，请打开下拉菜单“Build Book”。

(ref:bookdown-build)

图8.2: (ref:bookdown-build)

8.3.2 预览章节（Preview a chapter）

当书的大小很大或书中包含大量计算时，构建整本书可能会很慢。我们可以在bookdown中使用preview_chapter()函数一次只构建一个章节。同样，你也可以点击RStudio中的Knit按钮。

8.3.3 实时预览（Serve the book）

你可以使用bookdown::serve_book()函数来实时预览图书，而不是每次想要查看更改时都运行render_book()或preview_chapter()。任何时候保存Rmd文件，书将自动重新编译，预览将更新以反映变化。

8.3.4 RStudio 插件（RStudio addins）

bookdown包为RStudio提供了两个插件，可以帮助编辑书籍:

  • “Preview Book”:这个调用bookdown::serve_book()函数来编译并提供这本书。
  • “Input LaTeX Math”:提供了一个文本框，允许你写LaTeX方程，以避免在输入原始LaTeX数学表达式时常见的错误。

8.4 项目结构

下面是一个默认的bookdown项目的基本结构:

directory/
├──  index.Rmd
├── 01-intro.Rmd
├── 02-literature.Rmd
├── 03-method.Rmd
├── 04-application.Rmd
├── 05-summary.Rmd
├── 06-references.Rmd
├── _bookdown.yml
├── _output.yml
├──  book.bib
├──  preamble.tex
├──  README.md
└──  style.css

  • index.Rmd: 这是唯一包含YAML frontmatter的Rmd文档

  • Rmd files: 一个典型的bookdown 图书包含多个章节，每个章节都存在于一个单独的Rmd文件中。

  • _bookdown.yml:bookdown的配置文件

  • _output.yml:指定HTML、LaTeX/PDF和e-books的格式。

  • preamble.tex 和 style.css: 它们可以用来调整图书输出文档的外观和样式。需要具备具备LaTeX和/或CSS知识。

下面的小节将更详细地解释这些文件。

8.4.1 首页文件（Index file）

index.Rmd文件包含第一章和YAML元数据，例如:

---
title: "A Minimal Book Example"
author: "Yihui Xie"
date: "`r Sys.Date()`"
site: bookdown::bookdown_site
documentclass: book
bibliography: [book.bib, packages.bib]
biblio-style: apalike
link-citations: yes
description: "This is a minimal example of using
  the bookdown package to write a book."
---

其中在三个减号组成的两行之间的内容叫做YAML元数据， 是一本书的设置， 上例中有书的标题、作者名、日期（用R程序自动生成）、描述。 其中的site选项很重要， 一定要有这个选项， site: bookdown::bookdown_site使得RStudio软件能辨认这是一个bookdown图书项目， 从而为其提供一键编译快捷方式。 元数据中output项指定默认的输出格式。 documentclass项为借助LaTeX编译PDF格式指定LaTeX的模板， 现在还不能支持ctexbook模板所以使用了book模板。 bibliography项指定一个或者几个.bib格式的文献数据库。

8.4.2 Rmd文件（ Rmd files）

默认情况下，index.Rmd文件所有Rmd文件会共同渲染图书。Rmd文件必须是标题，如# 章节名，YAML元数据不应该包含在这些Rmd文件中，因为它继承index.Rmd文件。

默认情况下，bookdown按文件名的顺序合并所有Rmd文件，例如01-intro，将出现在02-literature.Rmd之前。以下划线_开头的文件名将被跳过。

  • 01-intro.Rmd

    # Introduction

This chapter is an overview of the methods that
we propose to solve an **important problem**.

  • 02-literature.Rmd

    # Literature

Here is a review of existing methods.

8.4.3 _bookdown.yml

_bookdown.yml文件允许你指定可选的设置来构建这本书。例如，你可能想通过包含rmd_files字段来覆盖文件合并的顺序:

rmd_files: ["index.Rmd", "02-literature.Rmd", "01-intro.Rmd"]

8.4.4 _output.yml

_output.yml文件用于指定图书输出格式(参 8.6)。下面是一个简单的例子:

bookdown::gitbook:
  lib_dir: assets
  split_by: section
  config:
    toolbar:
      position: static
bookdown::pdf_book:
  keep_tex: yes
bookdown::html_book:
  css: toc.css

8.5 Markdown extensions

bookdown包对中概述的Markdown语法进行了扩展，并提供了额外的功能强大的特性，以帮助更长的文档和学术写作。

8.5.1 公式编号

（1） 自动编号

首先把公式放在equation或align环境，其次使用语法(\#eq:label)给label命名。 其中label是自己给公式的文字标签，在bookdown中，公式标签必须以eq:开头。例如

\begin{equation}
  E=mc^2
  (\#eq:emc)
\end{equation}

E=mc2

\begin{align}
f(x) =& \sum_{k=0}^\infty \frac{1}{k!} x^k (\#eq:efunc-sum) \\
  = e^x (\#eq:efunc-ex)
\end{align}

f(x)=∞∑k=01k!xk=ex

（2） 手动编号

在用$$符号在两端界定的公式后面， 可以用命令增加人为的公式编号，如

$$
y = f(x)
\tag{*}
$$

y=f(x)

8.5.2 定理和证明（Theorems and proofs）

感觉不是很好用。

要写一个定理，你可以使用下面的语法:

```{theorem, pyth, name="Pythagorean theorem"}
对于直角三角形, 如果 $c$ 表示斜边的长度
，$a$ 和 $b$ 表示另外两条边的长度，则
$$a^2 + b^2 = c^2$$
```

定理8.1 (勾股定理) 对于直角三角形, 如果 c 表示斜边的长度 ，a 和 b 表示另外两条边的长度，则 a2+b2=c2

定理环境的变量包括:lemma引理、推论、命题、猜想、定义、例子、练习和假设。证明环境的变体包括注释和解决方案。这些环境的语法类似于定理环境，例如：

8.5.3 特殊标题（Special headers）

在bookdown中可以使用两种特殊类型的一级标题:

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

# (PART) 随机数和随机模拟 {-}

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

# (APPENDIX) 附录 {-}

8.5.4 文本引用（Text references）

[链接文本](#label)其中label是某个标题对应的标签。 结果产生一个链接，显示为链接文本，点击时跳到label对应的章节。

文本引用是带有标签label的段落。语法是(ref:label)text，其中label是唯一的标识符，而text是Markdown段落。例如:

(ref:foo)  **此处**定义一个文本引用

然后你可以使用(ref:foo)来引用全文。文本引用可以在文档的任何地方使用，在为图片指定长标题或在标题中包含Markdown格式时特别有用。例如:

一些文字

(ref:cool-plot)  **base** R中`iris`数据的箱线图

```{r cool-plot, fig.cap='(ref:cool-plot)'}
boxplot(Sepal.Length ~ Species, data = iris)

8.5.5 交叉引用

bookdown包扩展了R Markdown文档中的交叉引用，允许自动交叉引用节标题、表格、图形、方程和定理。这只适用于编号的环境，因此需要为图形和表格分配标签。交叉引用的格式是\@ref(type:label)，其中label是块标签，type是被引用的环境。为例:

  • 标题Headers:

    # 简介 {#intro}

参考见第 \@ref(intro) 章

  • 图:

    见图 \@ref(fig:cars-plot)

```{r cars-plot, fig.cap="随便起的图名"}
plot(cars)  # 一个散点图
```

  • 表格:

    见表 \@ref(tab:mtcars)

```{r mtcars}
knitr::kable(mtcars[1:5, 1:5], caption = "随便起的表名")
```

  • 定理

    See Theorem \@ref(thm:boring)

```{theorem, boring}
Here is my theorem.
```

  • 公式

    见公式 \@ref(eq:linear)

\begin{equation}
a + bx = c  (\#eq:linear)
\end{equation}

labels名只允许 (a-z, A-Z, 0-9), -, /,和 :

8.6 输出格式

bookdown 包括以下输出格式:

  • HTML:
    • gitbook
    • html_book
    • tufte_html_book
  • PDF:
    • pdf_book
  • e-book:
    • epub_book
  • Single documents:
    • html_document2
    • tufte_html2
    • pdf_document2
    • tufte_handout2
    • tufte_book2
    • word_document2

8.6.0.1 HTML

对gitbook格式， 即HTML网页格式， 编译完成后会弹出一个预览窗口， 其中的“Open in Browser”按钮可以将内容在操作系统默认的网络浏览器中打开。

另一种办法是在命令窗口用如下命令编译（以输出gitbook为例）， 我个人认为这种办法更好用：

bookdown::render_book("index.Rmd", 
  output_format="bookdown::gitbook", encoding="UTF-8")