1.5 HTML文档

rmarkdown中兼容HTML语法，这里仅补充Markdown语法未涉及到的部分。

如何查看网页元素：在一个HTML页面中，单击右键后选择’检查’（或者直接按’F12’），然后就会跳出网页元素界面。在单击左上角的按钮后，你就可以移到网页元素上查看相应的源码。

图 1.14: 查询网页元素

1.5.1 标签

超链接标签

在rmarkdown中写入[text](link)默认为<a href="link">text</a>，其中href表示超链接。若你想让超链接在新标签页打开，有如下三种方法：
- 直接在<a>标签中修改
  
  <a href="link" target="_blank">text</a>，其中target="_blank"表示跳转方式为在新标签页打开。这只针对一个超链接。
- 添加<base target="_blank">
  
  在正文开头处添加<base target="_blank">，即可让该HTML页面中的所有超链接均在新标签页中打开。
- lua过滤器
  
  你现在看到的这本笔记是由bookdown将一个个HTML文档组合而成，所以我采用了lua过滤器，使得Pandoc在编译文档时能够自行为所有超链接添加target="_blank"属性。请参考下述lua文件（新建txt文件，扩展名改成’.lua’即可）。
```
function Link(el)  
  if el.tag == 'Link' then  
    el.attributes.target = "_blank"  
  end  
  return el  
end  

return {  
  {Link = Link}  
}
```
  同时你需要在YAML中声明。
```
# 对于gitbook就是在_output.yml中
bookdown::gitbook:
 pandoc_args: ["--lua-filter=/path/to/your/lua_filter.lua"]

# 对于普通rmarkdown文件就是在开头的YAML中
output: 
  html_document：
    pandoc_args: ["--lua-filter=/path/to/your/lua_filter.lua"]
```
  关于lua过滤器详情可参考Pandoc Lua Filters
  
  除了添加网页的超链接外，还能提供本地文件的下载链接，形如<a href='path/to/your/file.zip'>下载文件</a>
下划线标签

<u>text</u>

1.5.2 目录

在HTML输出中，你可以在元数据处声明添加目录（table of contents，toc）及相关设置。

注意布尔值得用小写，且冒号后面得有空格

toc: true/false

是否生成目录。
toc_float: true/false

是否设置悬浮目录。若为true，则目录会在页面的左侧一栏，跟随页面移动；若为false，则目录将会固定在文档开头。

还可以为其添加更为细致参数，collapsed和smooth_scroll。
- collapsed: true/false
  
  默认为true。若为true，则目录将会被折叠；若为false，则目录会被完全展开。
- smooth_scroll: true/false
  
  默认为true。当你点击目录时，若为true，则会丝滑地滚动到目标位置；若为false，则会生硬地跳转到目标位置。
toc_depth: int

整数，设置目录深度。例如若为3，则最多只显示到三级标题。

---
title: 'TOC'
output: 
  html_document:
    toc: true
    toc_depth: 3
    toc_float: 
      collapsed: true
      smooth_scroll: true
---

1.5.3 外观

和目录一样，你可以在元数据处声明主题、语法高亮及CSS样式。

theme

控制文档的主题。除了默认default外，其余可选值为bootstrap、cerulean、cosmo、darkly、flatly、journal、lumen、paper、readable、sandstone、simplex、spacelab、united、yeti，还可以传入null不使用任何主题。

个人青睐default。
```
---
title: 'theme'
output:
  html_document: 
    theme: default
---
```
highlight

控制语法高亮的样式。除了默认default外，其余可选值为tango、pygments、kate、monochrome、espresso、zenburn、haddock、breezedark、textmate，还可以传入null不使用任何语法高亮。

个人青睐textmate。
```
---
title: 'theme'
output:
  html_document: 
    highlight: textmate
---
```
css

css样式既可以在主题和语法高亮设置好之后对特定部分起作用，也可以另辟蹊径（为theme和highlight传入null），即完全的自定义。

引入css样式有如下几种方法：
1. 内联样式，即直接添加在HTML的标签里，如<h1 style='text-align:center'>一级标题</h1>'>表示居中的一级标题。
2. 内部样式，在正文开头处将自定义样式写在<style>自定义样式</style>标签内。
3. 外部引入，在元数据处即可声明引入外部的.css文件（一般名为’style.css’）。第三种方法便于管理，因此较为常用。
```
---
title: 'css_style'
output: 
html_document: 
  css: style.css
---
```
1. 嵌入代码块，即将代码块的引擎更换为css，并在内部定义css样式。
```
```{css, echo=FALSE}
 p.caption {
   color: #777;
   margin-top: 10px;
 }
 ```
```
你可以在网页源码中找到文本、图片、表格等元素所处的标签，然后通过css样式来对其进行自定义。网上关于css样式的文章还是挺多的，例如你可以在CSDN里查询相关资料，这里就不再赘述了。

1.5.4 选项卡

# 标题{.tabset}会将其所有的子章节转变为选项卡，你可以在不同选项卡之间切换。在.tabset后面，你可以接着添加属性.tabset-pills和属性.tabset-fade。前者会让选项卡的背景变为深蓝色，后者会让选项卡的内容渐入（注意属性之间得用空格隔开）。一般情况下，会默认显示第一个选项卡。如果你想优先显示某一个选项卡，那么你可以在对应的子章节标题后面添加’{.active}’。当你结束编辑选项卡时，需要输入与上级标题同样多的#与{-}

### 上级标题 {.tabset .tabset-pills .tabset-fade}

#### 选项卡1

正文

#### 选项卡2

表格

#### 选项卡3 {.active}

图片

### {-}

图 1.15: 选项卡

1.5.5 表格

你可以在元数据处用df_print声明用哪种方式呈现表格，可选值有default、kable、tibble、paged和自定义函数，其中default为data.frame类型的表格。这些可选值本质就是调用相应的函数来打印表格。

---
title: 'df_print'
output: 
  html_document: 
    df_print: kable
---

df_print: default

等价于调用data.frame()函数来输出表格。

# df_print: default
data.frame(head(iris))

##   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
## 1          5.1         3.5          1.4         0.2  setosa
## 2          4.9         3.0          1.4         0.2  setosa
## 3          4.7         3.2          1.3         0.2  setosa
## 4          4.6         3.1          1.5         0.2  setosa
## 5          5.0         3.6          1.4         0.2  setosa
## 6          5.4         3.9          1.7         0.4  setosa

df_print: kable

等价于调用knitr::kable()函数来输出表格。

# df_print: kable
knitr::kable(head(iris))

Sepal.Length	Sepal.Width	Petal.Length	Petal.Width	Species
5.1	3.5	1.4	0.2	setosa
4.9	3.0	1.4	0.2	setosa
4.7	3.2	1.3	0.2	setosa
4.6	3.1	1.5	0.2	setosa
5.0	3.6	1.4	0.2	setosa
5.4	3.9	1.7	0.4	setosa

df_print: tibble

等价于调用tibble::tibble()函数来输出表格。

# df_print: tibble
tibble::tibble(head(iris))

## # A tibble: 6 × 5
##   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
##          <dbl>       <dbl>        <dbl>       <dbl> <fct>  
## 1          5.1         3.5          1.4         0.2 setosa 
## 2          4.9         3            1.4         0.2 setosa 
## 3          4.7         3.2          1.3         0.2 setosa 
## 4          4.6         3.1          1.5         0.2 setosa 
## 5          5           3.6          1.4         0.2 setosa 
## 6          5.4         3.9          1.7         0.4 setosa

df_print: paged

等价于调用rmarkdown::paged_table()函数来输出表格。

# df_print: paged
rmarkdown::paged_table(iris)

df_print: paged还可以同代码块一样在{r}中添加额外的参数来进行精细化输出。相应的参数如下：

选项	用途	默认值
max.print	打印行数的上限	1000
rows.print	每页展示几行	10
cols.print	每页展示几列	10
cols.min.print	每页至少展示几列	-
pages.print	表格下方有几个索引页数	-
paged.print	是否使用分页表格	TRUE
rownames.print	是否要打印行名	TRUE

个人感觉，从观感上来看，首先就可以排除掉default和tibble了，剩下kable和paged。我试过了，kable不能像paged一样在{r}中添加额外的参数，加之df_print的本质是调用函数，所以我打算放弃掉df_print这个选项，直接在打印表格时用knitr::kable()或者rmarkdown::paged_table()来进行精细化输出。

1.5.6 代码块及其输出

代码块及其输出的样式可以在{r}中进行设置。其中，class.source用于控制代码块的样式，class.output用于控制文本输出的样式。部分可选样式如下："bg-primary"、"bg-success"、"bg-info"、"bg-warning"、"bg-danger"。

或者，你也可以自定义CSS样式（如何引入css样式详见1.5.3节），为代码块或输出分配新的类名。

图 1.16: 自定义代码块及其输出样式

在代码块的设置中，echo允许在文档中是否呈现源码。但有些时候，你可能一开始需要隐藏代码，而在有需要的时候再显现出来。这就得依靠在元数据处的code_folding选项。当code_folding: show时，会显示所有的代码；当code_folding: hide时，会隐藏所有的代码。无论是显示还是隐藏，在文档开头处以及各个代码块旁边都会提供选项，来让你手动选择是’显示’还是’隐藏’代码。

---
title: 'code_folding'
output: 
  html_document: 
    code_folding: hide
---

当然，code_folding选项是对所有代码块而言的，你可以针对性地让某些代码块隐藏或展示。在{r}中，当code_folding: hide时，你可以通过class.source='fold-show'来让该代码块展示出来；当code_folding: show时，你可以通过class.source='fold-hide'来让该代码块隐藏起来。遗憾的是，code_folding只能够控制部分引擎的代码块（例如{r}、{python}、{stan}…），并不能控制{css}，此时，只需要在{css}中传入class.source='foldable'即可，即{css, class.source='foldable'}。

你也可以为代码块及其输出添加滚动条来限制它的高度。在HTML输出中，你可以在{css}代码块中添加max-height和overflow-y来限制代码块的高度及添加竖向滚动条。

```{css, echo=FALSE}
 pre {
   max-height: 300px;
   overflow-y: auto;
 }
 
 pre[class] {
   max-height: 100px;
 }
 ```

由于代码块的内容一般是被包含在<pre class='r'></pre>，其输出则是被包含在<pre></pre>里。因此上面的{css}样式表达的意思是对于所有的<pre>标签，限定最大高度为300px，同时添加竖向滚动条，而对于拥有类属性的<pre>标签，则限定最大高度为100px，也就是将前面的300px限定高度给覆盖掉了。最终呈现的效果就是代码块及其输出如果超过它们的限定高度，则都会添加竖向滚动条，其中代码块的限定高度为100px，输出的限定高度为300px。当然，你也可以自定义新的类，对特定的代码块（class.source）或输出（class.output）添加竖向滚动条。

```{css, echo=FALSE}
 .scroll-style {
   max-height: 300px;
   overflow-y: auto;
 }
 ```

1.5.7 添加HTML文件

你可以自行创建相关的HTML文件，在用rmarkdown输出核心HTML文件前导入这些HTML文件，从而丰富核心HTML文件的内容。

in_header

在HTML文件的<head>部分中包含的内容。这通常用于添加自定义css样式或元数据。
before_body

在HTML文件的<body>标签之前包含的内容。这可以用于添加自定义的HTML、JavaScript或其他内容。
after_body

在HTML文件的<body>标签之后包含的内容。这同样可以用于添加自定义的HTML、JavaScript或其他内容。

注意HTML文件应当与.Rmd文件处于同一个目录中

---
title: 'includes'
output:
  html_document:
    includes:
      in_header: header.html
      before_body: doc_prefix.html
      after_body: doc_suffix.html
---

1.5.8 Pandoc参数

有时候你需要使用Pandoc的内容来丰富你的输出文件，可能这些内容并不会在元数据处有专门的选项供你选择。此时，你可以通过pandoc_args来传入你需要的内容。这在1.5.1节中介绍lua过滤器时已经有所提及。更多的内容请参考Pandoc手册。

1.5.9 共享选项

可能你的多个rmarkdown文件都会有相同的output设置，此时，你可以在同一个目录下新建_output.yml文件。在该文件中，和平时的rmarkdown文件不同，你不需要有---和output，直接写相应的选项即可。示例如下：

html_document:
  toc: true
  toc_float: true
  toc_depth: 3
  highlight: textmate
  pandoc_args: ["--lua-filter=lua_filter.lua"]

1.5.10 下载文件

你可以在元数据处声明code_download: true，来为读者提供一个下载按钮，从而下载HTML文件的源代码，即.Rmd文件。

output:
  html_document:
    code_download: true

除了下载源代码外，还可以下载任意文件。在第1.5.1节已经提及到利用超链接来提供下载链接，这里将介绍如何利用xfun包中的函数提供下载链接。在使用前需要有这些包提供支持。

xfun::pkg_load2(c("htmltools", "mime"))

xfun::embed_file()、xfun::embed_files()、xfun::embed_dir()分别用于在html文档中嵌入单个文件、多个文件、文件夹。使用时直接放在r代码块中运行即可。一般而言，对于这三个函数，你只需要用到path、name、text这三个参数。

path

提供文件路径或者文件夹路径。若为多个文件embed_files()，则提供字符串向量，其中每个元素为对应文件的路径。
name

下载文件的名称。一般默认即可，如果需要重命名的话，注意不要忘了文件名的后缀，下载多个文件或者文件夹时需要以压缩包的形式，如.zip。
text

超链接的文本。