1 介绍

本文主要目的是介绍如何用R Markdown撰写学术类型的文档，权当资料整理供参考。

主要内容包括：

（一）简单介绍R Markdown及需安装的软件和设置；

（二）简单的学术类文档（结构简单，不需要交叉引用，如理工科课程作业等）；

（三）完整的学术类文档（结构完整，篇幅不长，但需要交叉引用，如学术论文等）¹；

（四）撰写长篇幅的学术类文档（全文需分章节，篇幅较长，需要跨章节的交叉引用，如书籍、学位论文等）；

（五）中文参考文献的样式；

（六）介绍R Markdown的具体用法。

1.1 什么是R Markdown？

R Markdown (Allaire et al. 2018) 是结合 Markdown 和 R(R Core Team 2018)语言的写作软件。

Markdown是轻量级、纯文本、超简单的书写格式。

R Markdown可以做什么？

• 语法简单。作者基本上无需关心排版问题，只要专心写作就可以了。
• 计算结果动态生成。作者不必手动拷贝粘贴代码结果或者生成的表格、图片等。
• 易于修改。写作过程中如需修改某处，全文相应变动会自动生成，包括软件运行的结果（图形等）。
• 比Word更美观，比LaTeX更易用。
• 方便地插入目录、图表、脚注等。Bookdown扩展功能可以交叉引用、索引。
• 方便地插入数学公式、参考文献、R代码。
• 可以生成漂亮的pdf、word、epub、网页和幻灯片等多种文件格式。
• 写作及结果具有可重复性。
  
• 支持多语言，包括 R, C/C++, Python, Fortran, Julia, Shell scripts和 SQL等。
• R 和 Markdown 都是开源免费的。

R Markdown使得数据分析代码可以与文档混编，具体语法请参看我另一个博客R Markdown 简介。

下面是回归模型的简单例子。在R中，回归模型可以用非常简单的一行代码搞定：lm(y~x, data)，计算结果可以在正文直接调用。

options(digits = 4)
fit = lm(dist ~ speed, data = cars)
coef(summary(fit))

##             Estimate Std. Error t value  Pr(>|t|)
## (Intercept)  -17.579     6.7584  -2.601 1.232e-02
## speed          3.932     0.4155   9.464 1.490e-12

b = coef(fit)

上面回归方程中的斜率可以用r b[2]调用，斜率为\(b=3.9324\), 完整的回归方程为： \[ Y = -17.5791 + 3.9324x\]

可用如下代码极为简单地做出散点图和回归直线：

plot(cars, pch = 19)
abline(fit, col = "red")

Figure 1.1: cars数据散点图以及回归直线。

2 用 R Markdown 写简单文档

所谓“简单”学术文档，是指满足了学术文档的基本要求，包括标题、公式、图表、参考文献以及自动编号等，但是不能交互引用。这种情况下 R Markdown 具有独特优势，可以直接上手，输出结果丰富。

1. 新建一个R Markdown 文档。在打开界面可输入题目和作者姓名，输出格式可选择html，pdf 或 word。

2. 简单设置。点击Knit旁边的齿轮按钮，在Output Options可做更多选择，比如可勾选Include table of contents，表示建立目录。勾选Number section headings表示章节题目包含顺序数字。在Figures勾选Render figure captions表示图形会显示标题并自动排序。

3. 结果输出。

• 如果文档是纯英文的，可以通过 knit 转为 html，pdf 或 word 任何格式都没问题。不过，如果你用中文Windows，则日期最好用 "` r Sys.Date() `" 代替或直接输入英文日期，否则可能会乱码。注意：pdf文档中不能出现任何中文字符，包括标点符号。
• 如果文档是中文的，则
  • 转 html 没有任何问题。
  • 转word，一定要在开始时指定，或在文档的output:下面指明word_document:，否则标题和日期会是乱码。
  • 中文文档不能直接转pdf，需要加装软件包并正确设置。

一般文档开头（称为yaml）是这样的：

---
title: "Title"
author: "Your Name"
date:  "2020-02-02"
output: 
  html_document:                           #文档格式为html
    fig_caption: yes                       #包括图形标题
    number_sections: yes                   #章节数字顺序
    toc: yes                               #显示目录
    toc_depth: 3                           #三级目录
    toc_float: True                        #目录作为侧边栏
  pdf_document:                            #文档格式为pdf
    fig_caption: yes
    keep_tex: yes
    latex_engine: xelatex
    number_sections: yes
    toc: yes
  word_document:                           #文档格式为word
    fig_caption: yes
    toc: yes
bibliography: reference.bib                #参考文献文件名
bibli0-style: apalike                      #参考文献格式
link-citations: yes                        #参考文献链接
colorlinks: yes                            #链接颜色
#lot: yes                                  #表格列表
#lof: yes                                  #图形列表
---

中文pdf文档

首先要确保已经安装bookdown，因为中文pdf文档需要用到rticles，tynytex等软件包。中文pdf文档还需要用到LaTeX套件，如Texlive，MikTex等。安装bookdown后，这些套件是否还需要安装，我不能确定。

创建简单的中文pdf文档，很简单：打开 R Markdown时，选择 From Template，从模版中选择 CTex Documents即可。

3 用 R Markdown 写学术文档

前面介绍的R Markdown文档是没有交叉引用功能的，即公式、图形、表格或章节之间在正文不能交互引用。

为了实现交叉引用功能，可以扩展到bookdown。但是bookdown需要建立一个文件夹，里面有一堆文件夹和文件，还要每章（节）单独写一个Rmd文件，有点复杂。除非你写书或硕博毕业论文，一般不太长的文档或杂志论文没有必要。解决办法是把bookdown用单个文件的格式(Xie 2018a)，也具有交互引用功能。

一个合适的设置需要满足：

1. 标题、图形、表格、公式等可以自动编号，可以交互引用；
2. 一个文档可以输出html、pdf和word等多种格式；
3. 参考文献可以方便地修改样式。

我的 yaml是这样的（满足以上三个条件）：

---
title: "如何用 R Markdown 写学术文档？"
author: "Shujia Wong"      
#date:  "2020-02-02"
date: "2020年02月02日"
#geometry: left = 3.18cm, right = 3.18cm, top = 2.0cm, bottom = 2.0cm
#fontsize: 12pt
output: 
  bookdown::gitbook:
    config:
      toc: 
        collapse: subsection
    self.contained: yes
    table_css: TRUE
    number_sections: TRUE
    split_by: none
  bookdown::pdf_document2: 
    keep_tex: yes
    dev: "cairo_pdf" # Allow Chinese figure title and labels
    latex_engine: xelatex # for chinese
    template: template/template_article_zh.tex   #latex template
    #pandoc_args:  --top-level-division=chapter
    fig_caption: yes
    number_sections: yes
    toc: yes
    toc_depth: 3
    #toc_unnumbered: no
    #toc_appendix: yes
    quote_footer: ["\\begin{flushright}", "\\end{flushright}"]
  bookdown::html_document2: 
    css: bib/style.css
    fig_caption: yes
    theme: readable
    #highlight: monochrome
    number_sections: yes
    toc: yes
    toc_depth: 3
    toc_float: True #目录作为侧边栏
  bookdown::word_document2: 
    reference_docx: template/reference_word.docx
    fig_caption: yes
    toc: yes
    toc_depth: 3
citation_package: natbib
bibliography: [bib/packages.bib,bib/book.bib]
#csl: bib/chinese-gb7714-1987-numeric.csl
bibli0-style: apalike
link-citations: yes
colorlinks: yes
#lot: yes
#lof: yes
---

注意，要在工作目录中创建两个子目录：

• template子目录，存放样板文档。template_article_zh.tex来自bookdownplus(Zhao 2017)，并且稍作修改。reference_word.docx是本人制作，你可以根据需要修改word的样式。
• bib子目录，存放参考文献（.bib）和式样文件(.csl)。

4 用Bookdown写书或长文

5 修改中文参考文献样式

不管是 Bookdown 还是 Bookdownplus，默认参考文献的引用格式都是 apalike，引用格式是作者-年，不符合gb7714中文标准。

如何把参考文献修改为中文标准格式？

6 总结

本文简单介绍了如何用R Markdown写一般性研究短文（标题、公式、图表、参考文献等都能自动排版和编号）、中等篇幅的研究论文（可以交互引用）和长篇幅的研究文章（书籍、研究报告、学位论文等）等。

用R Markdown写研究性文章最大的优点是可以把数据分析的过程（不局限于R，也可以是Python等）和文章文本结合起来，写作过程中可以方便地进行修改，保持文章结果的可重复性。

LaTeX的一些前端（如LyX）也可以做到R运行与文本的结合，但必须全文编译后才能看到结果，不如R Markdown方便，可以在中间过程运行R代码块，随时查看部分计算结果。

总之，R Markdown简单易学，是做学习笔记、科学研究、撰写论文和书籍的好工具，值得花时间掌握。