rmarkdown.md 4.3 KB
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文件中，通过以下方式围栏代码区域从而嵌入代码块：
1+1
R代码块也可以具有标签并指定处理选项：
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 $$用以插入行间公式
- 用以插入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包则需要提前手动完成编码的转化。