### R markdown（中文翻译）

#### 概述

R markdown是R语言运行环境RStudio所使用的扩展的markdown标签语言，能够方便的利用R语言生成web格式的报告。它包括核心的Markdown语法，并能将其中插入的R代码区块的运行结果显示在最终文档里。
R Markdown标签被描述为以下几个部分的集合：
* 核心的Markdown语法
* 能够插入R代码并显示其运行结果
* 来自于Sundown的扩展Markdown语法
* 支持LaTeX和MathML格式的公式
* 将图片打包进生成的HTML格式文件

#### 实现

R markdown的实现需要以下两个包：  
* knitr——将RStudio的Rmd格式文件编译为markdown格式
* markdown——将markdown文件转化为HTML文档

在RStudio中Knit HTML命令可以将R markdown文件直接渲染成HTML。而实际上Rmd转化到HTML的过程是分两步的，第一步将RStudio的Rmd格式文件编译为markdown格式，第二步将markdown文件转化为HTML文档，其中第二步允许使用其他的markdown渲染程序，如pandoc。若使用其他markdown渲染程序，应使用相应的markdown扩展语法。

#### 标签

在第一步中核心markdown语法和R代码区块是始终有效的。第二步中则使用的是RStudio及其markdown包来转化markdown到HTML。如果使用其他的markdown程序替代，如pandoc，则需要注意其不同的扩展语法。

#### 核心markdown

核心markdown语法通过纯文本格式化命令描述了一系列广泛的文本结构，包括标题、字词强调、有序和无序列表、链接、插图以及行内代码等。R Markdown执行全部的核心markdown语法（两个例外见于下文Sundown扩展项中）。  
详细语法描述见于markdown语法定义中。

#### 嵌入R代码

在R Markdown文件中，通过以下方式围栏代码区域从而嵌入代码块：
```{r}
1+1
```
R代码块也可以具有标签并指定处理选项：

```{r md-cars-scatter, message=FALSE, fig.width=7, fig.height=5}
library(ggplot2)
qplot(hp, mpg, data=mtcars)+geom_smooth() 
```
将R表达式紧接在r后并用两反单引号括起，可在行内计算R表达式，如：

I counted `r 1 + 1` red trucks on the highway.  
当R代码运行结果被展示在最终的HTML文件中，会出现对比的背景色和语法高亮。R代码的原文本也会被被显示在方框中。

#### Sundown 扩展

RStudio的markdown包使用Sundown库将markdown渲染为HTML。Sundown支持核心markdown，Github flavored markdown的一系列扩展，以及若干附加的扩展语法。

Github flavored markdown扩展语法包括以下：

* 在字符间的连续下划线（如perform_complicated_task）不被当做一种格式
* URLs的自动连接
* 使用```围栏代码区域

附加的扩展语法包括：  
* 文档顶端的Pandoc题目区块和YAML扉页被忽略
* 支持PHP Markdown Extra语法定义的表格
* 支持上标（如superscript^2）
* 支持删除线（如 strikethrough）

最后，一下ASCII字符序列会被转化为印刷体的HTML实体字符：  
* 直引号（'和"）被转为曲引号
* 反引号被转化为曲引号
* 破折号（--和---）转化为短连接线和破折号实体字符
* 三个连续的点（...）转化为省略号实体字符
* 分数如1/4，1/2和3/4转化为¼, ½, and ¾
* 符号(c)，(tm)和(r)转化为©，™和®

#### LaTeX和MathML公式

用以下语法插入LaTeX和MathML公式：  
* $equation$用以行内公式（注意$后不能加空格）
* $$ equation $$用以插入行间公式
* <math ...> </math>用以插入MathML公式

关于插入公式更详细的信息见文章Equations in R Markdown中。

#### 打包图像

当markdown被转化为HTML时，文件中用相应超文本指定的图像将直接被打包进最终生成的HTML文件中。这个过程产生一个独立的web页面，在分享时不需要再打包任何其他附件文件。可以将生成的HTML文件作为邮件附件，在公共文件夹中分享，或者在web服务中将其配置成单独的HTML文件。
打包图像的过程是基于base64编码图像，然后使用data URI插入被编码的图像。

#### 文本编码

Sundown库使用UTF-8编码读写文本内容。因此将UTF-8作为Rmd文件的编码是最方便的。RStudio也支持其他的编码（在利用Sundown渲染之前RStudio会将其他编码转化为UTF-8），然而如果直接使用markdown包则需要提前手动完成编码的转化。