3月 152017
 

快速开始

R bookdown 是什么

  • 一个用来写书写文章的软件。
  • 比Word更美观,比LaTeX更易用,比Markdown格式更丰富。
  • 可以方便地插入目录、图表、交叉引用、脚注、索引。
  • 可以方便地插入公式、参考文献、R代码。
  • 可以生成漂亮的pdf、word和网页文件。
  • 撰写可重复性报告的不二之选。

安装

  1. 下载R并安装。
  2. 下载RStudio并安装。
  3. 下载CTEX并安装。建议安装完整版。
  4. 下载Pandoc并安装。
  5. 运行RStudio。在左上面板的代码窗口输入并运行以下代码(安装bookdown扩展包):
install.packages("bookdown")

好了,安装完毕。

从模板开始

  1. 下载模板文档(到下载页面点击Clone or downloadDownload ZIP):
  1. 将模板文档解压缩到任意文件夹。

  2. 在解压缩后得到的文件里找到扩展名为.Rproj的文件。双击,默认会用RSudio打开。

  3. 在RStudio右上面板点击Build标签,再点击build book。好了,模板书出现在名为_book的子文件夹里。

  4. 在RStudio右下面板里会看到该文件夹里的文件,其中有一些扩展名为.Rmd的文件。逐个点击打开,把其中的内容修改成你自己的内容。除了index.Rm外,不需要的.Rmd文件可以删掉。

  5. 重复第4步,就得到了你自己的书。

  6. 对照一下.Rmd的文件内容和生成的文档,体会两者之间是如何对应的。

基本标记

标记 输出
*斜体* 斜体
**粗体** 粗体
CO~2~ CO2下标
R^2^ R2上标
$E = mc^2$ \(E = mc^2\) 行内公式(双美元符号为行间公式)
[大鹏志](http://dapengde.com) 大鹏志超级链接
<dapengde@live.com> dapengde@live.com 邮件链接
![](http图片链接) 插入图片
> 引用文字 引用
`代码` 代码
# 第一章 章节标题
1. 首先,... 带编号的列表
- 首先 不带编号的列表
^[脚注] 脚注

章节划分、编号和交叉引用

# (PART) Part I {-} 
# (APPENDIX) Appendix {-} 
# References {-}
# chapter {#ID}
## section {#ID}
# chapter {#ID .unnumbered}

\@ref(ID)

图表

第一种插图:嵌入的R代码作图:

```{r, fig.cap='caption', out.width='80%', fig.align='center', echo=FALSE}
plot(1:10)
```

\@ref(fig:fig1)

第二种插图:将现成的图片文件插进来:

```{r img1, fig.cap='caption', out.width='80%', fig.align='center', echo=FALSE}
knitr::include_graphics("images/img1.png")
```

\@ref(fig:img1)

第三种插图:用markdown基础语法:

!(images/img1.png)

第一种表格:直接用markdown语法画表格。输入:

第一列标题  第二列标题
----------- ----------
第一行1     第一行2
第二行1     第二行2

输出:

第一列标题 第二列标题
第一行1 第一行2
第二行1 第二行2

第二种表格:用R函数展示表格:

```{r tab1, tidy=FALSE, echo=FALSE}
knitr::kable(
  head(iris, 20), caption = 'Here is a nice table!',
  booktabs = TRUE
)
```

\@ref(tab:tab1)

参考文献

参考文献信息需要保存在.bib文件里。

引用文献条目:[@R-bookdown]

参考文献列表:# References {-}

生成R包参考文献库:

knitr::write_bib(c("knitr", "stringr"), "", width = 60)

定义、定理、示例等环境

环境全称:theorems   lemma   definition  corollary   proposition example
引用简称:thm          lem   def         cor         prp         ex
```{环境全称, label='', name=""}
内容
```

\@ref(引用简称:label)

输出word文档

在_output.yml里添加一行:

bookdown::word_document2: default 

注意,default这个词是不能少的。

公式编号和引用

word文档里的公式的编号和交叉引用,可以使用行内公式,公式前用圆括号里加公式标签。例如,输入:

(@eq-mc) $E = mc^2$

I like Eq. (@eq-mc) so much that I am falling love with her.

得到:

  1. \(E = mc^2\)

I like Eq. (1) so much that I am falling love with her.

pdf文档里的公式编号和交叉引用,建议使用公式环境。例如,输入:

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

I like Eq. \@ref(eq:mc2) so much that I am falling love with her.

更进一步

bookdown的详细介绍见使用手册。我的使用体验写成了三篇帖子:

  15 Responses to “R bookdown 快速入门和语法速查”

  1. 尊敬的大鹏老师,您好!
    我下载pandoc的时候总是失败,您能否将windowns系统用的pandoc发到我的邮箱里面,谢谢。

    • 你好。抱歉,我的邮箱不允许发送可执行文件。请试试别的断点续传下载工具吧。

  2. 博主,你好。我在windows系统中总遇到以下两个问题,想向你请教你以下:

    解压“中文模板”后,双击扩展名为.Rproj的文件。RSudio提示以下错误,但是build能正常运行,不知道下面的错误提示是什么意思?

    Error in yaml::yaml.load(string, …) :
    Scanner error: mapping values are not allowed in this context at line 2, column 7

    Build Book生成pdf总是出现如下错误,而且不能生成正常的pdf文件,而其他文件类型都没有问题?

    Error: Failed to compile bookdown.tex.
    In addition: Warning messages:
    1: In readLines(input, encoding = “UTF-8″) :
    incomplete final line found on ‘_output.yml’
    2: running command ‘”xelatex” -halt-on-error -interaction=batchmode “bookdown.tex”‘ had status 127
    Execution halted

    Exited with status 1.

    • 你的yaml里第2行第7列是不是有中文字符?我在bookdown的项目主页上汇报过类似的问题
      pdf无法生成的话,建议查看一下.log文件,看看具体是哪里出错了。
      最后,建议你来bookdown项目主页来讨论,方便更多的人看到。

      • 首先,非常谢谢。起初,没有在bookdown这个项目报告问题,是因为英语不过关,担心不能表述清楚问题(还要好好学习English)。现在,在bookdown的中文模板下用中文提出了问题,谢大也有回应了。我还有个小疑问,那个.log文件是个什么类型的文件呀?没有latex基础,完全看不懂,更别说找出错误在哪里了,哎。

        • .log是个文本文件,记录的是.tex文件的编译情况。如果编译失败,那么会在文件末尾显示是.tex第几行出现了错误。没关系,不懂就把信息贴出来问就是了,大家都是这么干的。最差的结果不就得没人里嘛……

        • 谢谢啊,你说的非常好。
          另外,还有两个问题请教你一下。
          1. 想请问你一下pandoc和ctex软件在其中有什么用途呀?可以简单理解为pandoc是负责把markdown文件转化为pdf,而ctex是为了支持中文吗?

          为什么按你给的通用版本能正常生成pdf类型文件,而中文模板总是出现如下错误

          这个目录下载到本地后,Build Book选择bookdown::gitbook能正常运行,但是选择bookdown::pdf_book总是产生如下错误:
          Use of uninitialized value in concatenation (.) or string at C:\ProgramFiles\CTEX\MiKTeX\scripts\latexmk\perl\latexmk.pl line 830.
          ! Undefined control sequence.
          \XeTeXLinkMargin

          Error: Failed to compile bookdown.tex. See bookdown.log for more info.
          In addition: Warning messages:
          1: running command ‘”C:\PROGRA~4\CTEX\MiKTeX\miktex\bin\latexmk.exe” -v’ had status 1
          2: The LaTeX package latexmk was not correctly installed.
          3: running command ‘”C:\PROGRA~4\CTEX\MiKTeX\miktex\bin\latexmk.exe” -v’ had status 1
          4: running command ‘”xelatex” -halt-on-error -interaction=batchmode “bookdown.tex”‘ had status 1
          Execution halted

          Exited with status 1.

          请问这是我的CTEX没有安装好,还是其它问题?我猜想应该不是软件版本的问题,因为下载https://github.com/rstudio/bookdown-demo 这个英文目录时,能够正常生成pdf文件。所有测试都是在windows系统下完成的。

          第二个问题,具有普遍性已经在Github上提交。

          1. pandoc 用来进行各种文档格式之间的转换。ctex是把.tex文件编译成.pdf。具体在bookdown里工具链是如何协同工作的,我有一些猜测,但怕猜错,建议还是问yihui靠谱。其实我不大关心pandoc和ctex各自的职责,只要bookdown生成的是我想要的就行了。
          2. 这个问题我在bookdown中文主页上提交过,已经解决了。
  3. 谢谢,按照里面的方法,问题已经基本解决。

  4. 师兄您好,
    我想用bookdown写一点化学的东西,网上查到MathJax的mhchem包可以很方便的输入化学方程式,但研究了很久也没有搞明白如何能把mhchem包加载到bookdown里,在此求助,谢谢!

    • 我只知道LaTeX有个mhchem包。如果你是想用bookdown生成pdf文档,那么在tex的导言区加载mhchem包就行了:

      \usepackage{mhchem}
      

      至于如何用MathJax加载,建议你来bookdown的Github项目主页咨询yihui。

  5. 请教大鹏先生,我现在有一批300人的数据,需要给每个人生成一个PDF报告(报告用同一个模板,仅数据不同),使用bookdown可以实现自动生成吗?如果可以大致需要哪些设置呢?

    • 当然可以。先做好一个人报告的 bookdown 模板文件,例如叫 body.Rmd;然后写一段 R 代码,来读入 body.Rmd,并将其中的 id 标识改为变量。在这段 R 代码里设置个循环,或者用 lapply,对 300 个 ID 批量处理就行了。

      我正在出版的新书《学 R》特别举了这样一个例子,批量生成文档报告。

      如果仍有疑问,请来 https://d.cosx.org/t/r 讨论,会有跟多的人帮助你,我们的讨论也会帮到更多人。

  6. 我正在出版的新书《学 R》特别举了这样一个例子,批量生成文档报告

 填写评论

To create code blocks or other preformatted text, indent by four spaces:

    This will be displayed in a monospaced font. The first four 
    spaces will be stripped off, but all other whitespace
    will be preserved.
    
    Markdown is turned off in code blocks:
     [This is not a link](http://example.com)

To create not a block, but an inline code span, use backticks:

Here is some inline `code`.

For more help see http://daringfireball.net/projects/markdown/syntax

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

(必填)

(必填)