index.Rmd

---
title: "R Markdown 指南"
author:
  - 高春辉
  - 王祎帆
  - 闫求识
  - 庄亮亮
  - 杨晓龙
date: "`r Sys.Date()`"
documentclass: ctexbook
bibliography: [book.bib, packages.bib]
biblio-style: apalike
link-citations: yes
colorlinks: yes
lot: yes
lof: yes
geometry: [b5paper, tmargin=2.5cm, bmargin=2.5cm, lmargin=3.5cm, rmargin=2.5cm]
site: bookdown::bookdown_site
description: "R Markdown 指南"
github-repo: cosname/rmarkdown-guide
always_allow_html: true
#cover-image: images/cover.jpg
---

# 前言 {-}

```{r, setup, include=FALSE}
if (knitr::is_html_output()) {
  # ignore percentage widths for HTML output, unless they are used for multiple
  # figures side by side
  knitr::opts_hooks$set(out.width = function(options) {
    if (options$fig.show != 'hold' && grepl('%$', options$out.width))
      options$out.width = NULL
    options
  })
}

options(bookdown.post.latex = function(x) {
  # substitute nonbreaking spaces in \texttt{} with normal spaces
  m = gregexpr('\\\\texttt\\{[^}]+}', x)
  regmatches(x, m) = lapply(regmatches(x, m), function(z) {
    gsub('\\\\ ', ' ', z)
  })

  # fix syntax highlighting:
  # \FunctionTok{tufte:}\AttributeTok{:tufte_html: default} ->
  # \FunctionTok{tufte::tufte_html:}\AttributeTok{ default}
  x = gsub('(\\\\AttributeTok\\{[^:]+:)(})(\\\\FunctionTok\\{)(:[^:]+:)', '\\1\\4\\2\\3', x)
  if (length(i <- grep('^\\\\begin\\{longtable\\}', x)) == 0) return(x)
  i1 = bookdown:::next_nearest(i, which(x == '\\toprule'))
  i2 = bookdown:::next_nearest(i, which(x == '\\endfirsthead'))
  x[i1 - 1] = paste0(x[i1 - 1], '\n\\begin{tabular}{', gsub('[^lcr]', '', gsub('.*\\[]', '', x[i])), '}')
  x[i] = '\\begin{table}'
  x[x == '\\end{longtable}'] = '\\end{tabular}\n\\end{table}'
  x[x == '\\endhead'] = ''
  # x = x[-unlist(mapply(seq, i1, i2, SIMPLIFY = FALSE))]
  x
})

options(tinytex.verbose = TRUE)
```

《R Markdown 权威指南》是第一本系统介绍 R Markdown 技术的中文图书。

## 为什么要写这样一本书？

R Markdown 是一个生产力工具。她基于流行的 R 语言，通过 **knitr**，**rmarkdown**， **bookdown**，**tinytex** 等一系列 R 软件包实现其功能。自 2012 年初 knitr 发布 以来，R Markdown 技术不断发展和丰富，已经成为当前制作动态文档、演示文稿、PDF 文档、建设网站，以及著书的主流工具之一。

基于 R Markdown 技术实现的动态文档，可以自行将文档内包含的代码编译执行，并将运行的结果（如绘图、控制台输出、LaTeX 数学公式、图片、源代码等）动态整合到最终文档中，最大程度上实现了技术文档的自动化。

与另一个流行的功能密切相关的生产力工具 Jupyter Notebook 相比，R Markdown 是 R 语言用户的第一选项。且R Markdown 在 RStudio 中具有原生支持，这大大降低了 学习的难度，提高了日常使用 R Markdown 的效率。另外，虽然R Markdown 基于 R 语言实现，但是她也支持在文档中使用 Python、Bash 等其它编程语言。

由于 R Markdown 具有上述种种优势，使其成为一种一旦掌握就能受益终身的通用技能。在学校，适合写作业，在职场，适合做工作汇报，在学术届，适合开展可重复研究等等。

现在网络上关于 R Markdown 的教程很多，但是对于一本图书而言，其系统、全面的优势是不可替代的。因此，在外文图书市场上有多部 R Markdown 技术书籍。其中，仅 Chapman & Hall 出版社（<https://www.crcpress.com/>） 已经先后出版了"[bookdown: Authoring Books and Technical Documents with R Markdown](https://bookdown.org/yihui/bookdown/)"、 "[R Markdown Cookbook](https://bookdown.org/yihui/rmarkdown-cookbook/)"，"[blogdown: Creating Websites with R Markdown](https://bookdown.org/yihui/blogdown/)"、"[R Markdown: The Definitive Guide](https://bookdown.org/yihui/rmarkdown/)"等多部以 R Markdown 技术为主要介绍对象的书籍。除此之外， 基于 R Markdown 进行技术类图书写作也成为日益流行的创作样式，包括本书以及上述书籍在内都是依托 R Markdown 技术创建的。R 语言的经典教材和书籍（如"R for Data Science"等）也都是如此（<https://www.bookdown.org/>）。然而，在中文图书市场上，尚没有任何一部系统介绍 R Markdown 的图书。

于是，我们就决定写了这本书。

## 本书是怎么写出来的？

本书是在谢益辉（[\@yihui](https://github.com/yihui)）组织下，由高春辉、王祎帆、闫求识、庄亮亮、杨晓龙等共同创作完成的。书籍的创作主要参考了谢益辉所著的《R Markdown Cookbook》 和《R Markdown: The Definitive Guide》等资料。但是书籍创作过程并非严格的编译，而是结合了作者在这一领域的经验和认识。

作者的基本信息如下：

-   高春辉：博士，华中农业大学资源与环境学院副研究员；
-   王祎帆：中国人民大学统计学院博士生，统计之都成员， 《R Graphics Cookbook》 的译者；
-   闫求识：范德堡大学数据科学研究生；
-   庄亮亮：浙江工商大学理学统计博士生，微信公众号"庄闪闪的 R 语言手册"主编，统计之都成员；
-   杨晓龙：东京大学政治科学的本科三年级。


## 本书的创作理念是什么？

本书的目的是让更多人受益于 R Markdown 技术。在写作的过程中，我们尽可能系统、全面地介绍 R Markdown 技术，并将最佳实践呈现给读者。实际上，本书就是用 R Markdown 进行写作的，在写作过程中我们遇到了很多问题，也新学习到了很多知识，这些都在各个章节有所体现，希望读者们能从中收益。

## 本书主要有哪些内容？

本书章节设置如下：

- **第一部分：初识 R Markdown**：本部分对 R Markdown 进行了简要介绍，本部分共包含两章：

  - 第 \@ref(rmarkdown-intro) 章：**R Markdown 概述**：本章简单介绍 R Markdown 的发展历程（第 \@ref(rmarkdown-source) 节），并以案例的形式介绍 R Markdown 的可能应用（第 \@ref(rmarkdown-example) 节）；

  - 第 \@ref(rmarkdown-base) 章：**R Markdown 的基础知识**：本章从 R Markdown 的相关配置（第 \@ref(rstudio-config) 节）、安装（第 \@ref(rmarkdown-install) 节）、编译过程（第 \@ref(rmarkdown-compile) 节），到其基本元素（第 \@ref(rmarkdown-element) 节）、页面设置布局（第 \@ref(page-layout) 节）、文档元素（第 \@ref(document-element) 节）等方面，为 R Markdown 初学者提供其相关知识；

- **第二部分：基于 R Markdown 的应用**：本部分介绍了基于 R Markdown 的基础应用，在学习完本部分，读者应能够使用 R Markdown 完成简单的学习或工作任务。本部分共包含两章：

  - 第 \@ref(rmarkdown-document) 章：**使用 R Markdown 创建常用文档**：本章介绍了如何使用 R Markdown 生成常用的 HTML（第 \@ref(rmarkdown-html) 节）、PDF（第 \@ref(rmarkdown-pdf) 节） 文档，甚至还包括如何生成 PPT（第 \@ref(rmarkdown-ppt) 节）、Word（第 \@ref(rmarkdown-word) 节） 以及新的文档输出格式（第 \@ref(rmarkdown-new) 节）。在学完本章后，可以正常使用 R Markdown 开展日常的很多工作。

  - 第 \@ref(rmarkdown-working) 章：**基于 R Markdown 工作与学习**：本章给出了一些在工作和学习场合使用 R Markdown 完成一些可能会很繁琐的工作，包括发邮件（第 \@ref(rmarkdown-email) 节）、制作 R 包（第 \@ref(rmarkdown-package) 节）、制作简历（第 \@ref(rmarkdown-cv) 节）、写书或记笔记（第 \@ref(rmarkdown-bookdown) 节）以及制作网页（第 \@ref(rmarkdown-blogdown) 节），本章针对科研工作者还介绍了如何使用 R Markdown 制作科技论文的支撑材料（第 \@ref(rmarkdown-paper) 节），从而帮助读者更全面地了解 R Markdown 的强大之处；

- 第三部分：R Markdown 进阶操作：本部分为具有一定 R Markdown 使用经验的读者提供了更丰富的内容，从而帮助读者使用 R Markdown 大大增加日常学习工作的便捷性。本部分共包含三章：

  - 第 \@ref(rmarkdown-interaction) 章：**使用 R Markdown 创建动态交互文档**：本章介绍了 R Markdown 如何与 Shiny、Dashboards 结合，生成 Web 交互界面（第 \@ref(rmarkdown-shiny) 节）以及交互式仪表盘（第 \@ref(rmarkdown-dashboards) 节），甚至在 R 包中也可以加入 R Markdown（第 \@ref(package-rmd) 节）。本章为第四章提供了补充。

  - 第 \@ref(rmarkdown-operation) 章：**R Markdown 的操作技巧**：本章介绍了一些 R Markdown 的进阶操作技巧，可以在很大程度上优化使用者以及报告读者的体验，包括表格的一些特殊操作（第 \@ref(table-advanced) 节）、R Markdown 中的块选项（第 \@ref(chunk-options) 节）以及与其它语言的结合（第 \@ref(other-language) 节）。另外还有三节介绍了输出钩子（第 \@ref(output-hook) 节）、缓存（第 \@ref(cache) 节）以及其它的小技巧（第 \@ref(other-trick) 节），供有一定使用经验的读者阅读。

  - 第 \@ref(rmarkdown-project) 章：**使用 R Markdown 开展项目工作**：本章的内容为第四章提供了更多的补充，并主要集中在项目管理（第 \@ref(work-flow) 节）以及工作流（第 \@ref(project-manage) 节）方面，可以帮助使用者在工作中大大提升工作效率。

## 阅读本书时的注意事项

1. 本书在编写过程中包含了很多例子，为了使读者能够清晰地理解，本书并没有给出这些例子的编译结果，而是以源代码形式更直白地展现给读者，希望读者自行编译，也可以加深对这些例子的理解。当然，在必要的地方我们也会以各种形式给出例子的编译结果；

2. 本书在编写过程中的一些内容可能并不能被所有读者轻易理解，本书在这些章节后面添加了“(\*)”。跳过这些章节也不影响整体阅读，如果想要更详细了解 R Markdown，或想提升使用 R Markdown 的能力，可以进一步阅读这些章节；

3. R Markdown 功能强大，可以实现很多功能，本书对于大多数常用功能进行了详细的解释，而对于一些更复杂的、受众相对较小的功能，本书仅对其进行了简要介绍，并提供了相应书籍甚至章节的名称以供读者查阅。