更新：Hugo v0.100.0 移除了 Blackfriday，目前 Hugo 只使用 goldmark。

这篇博文源自于 Yihui Xie 为 Hugo 主题 hugo-xmag 写的英文介绍 A Plain Markdown Post ¹。除翻译的内容外，补充了关于如何嵌入音频、视频和幻灯片的内容，也是这次 R 会上小伙伴们提问最多的地方。

这篇博文主要面向 blogdown 用户，如果你不使用 blogdown，你可以跳过第一节。想知道更多关于 Markdown 的基础语法，请看 John Gruber’s Markdown 语法和 R Markdown: The Definitive Guide。

这篇文章含有丰富的多媒体内容，需要有较好的网速环境，也需要科学上网才能获得最佳的阅读体验！

1. Markdown 还是 R Markdown

这篇博客是用纯 Markdown (*.md) 语法写的，而不是 R Markdown (*.Rmd)。其主要的区别是：

Markdown 文档中不能运行任何代码，而在 R Markdown 文档中，你可以插入这样的 R 代码块 (```{r})；
Markdown 文档通过 Hugo 内建的 Markdown 处理器 Blackfriday 渲染，R Markdown 文档需要先由 rmarkdown 和 Pandoc 编译转化生成 HTML 网页。

Pandoc 和 Blackfriday 一样都支持任务型列表²，而原始 Markdown 是不支持的

开发一个R包。
写一本书。
…
搭建个人博客！

Blackfriday’s Markdown 和 Pandoc’s Markdown 之间有很多区别。比如 Blackfriday 不支持 LaTeX 数学公式，而 Pandoc 支持。谢益辉在 hugo-xmin 主题中添加了 MathJax 支持，在 Markdown 文档中必须把数学表达式放在一对反引号中，行内公式： `$ $`；行间公式： `$$ $$`，举个小栗子， $S_n = \sum_{i=1}^n X_i$ ，$$S_n = \sum_{i=1}^n X_i.$$ 在 R Markdown 文档里，不需要反引号，因为 Pandoc 能识别和处理数学表达式。³

总的来说， Markdown、Hugo’s Markdown、Pandoc’s Markdown 和 R Markdown 的关系大致如下：

Markdown 家族

当你创建一篇新的博文时，我推荐你使用 RStudio 插件“新建博文” (New-Post)：

RStudio addin New Post

2. 样例文本

二级标题

三级标题

四级标题

一个有脚注的段落：

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.⁴

2.1 引用

下面插入一段引用，来自《红楼梦》第三回，林黛玉初到荣国府，曹雪芹对她的描写

两弯似蹙非蹙笼烟眉，一双似喜非喜含情目。态生两靥之愁，娇袭一身之病。泪光点点，娇喘微微。闲静似娇花照水，行动如弱柳扶风。心较比干多一窍，病如西子胜三分。

引用的左边有灰色条，背景是亮灰色，再引用名人名言

Essentially, all models are wrong, but some are useful.

— George Box

引用要被玩坏了，继续引用唐代诗人崔护的诗《题都城南庄》

去年今日此门中，人面桃花相映红。
人面不知何处去，桃花依旧笑春风。

在 Markdown 中引用诗词或歌词，请看这篇博文，还可以在 RStudio 里用 blogdown 提供的插件（Quote Poem）快速实现诗歌的引用

This is a block quote. This paragraph has two lines.

This is a list inside a block quote.

Second item.

嵌套引用

This is a block quote.

A block quote within a block quote.

2.2 插入代码

插入一些 R 代码，可以语法高亮和带下拉的阴影效果哦！

data(anscombe)
form <- paste(paste0("y", seq(4)), paste0("x", seq(4)), sep = "~")
fit <- lapply(form, lm, data = anscombe)
op <- par(mfrow = c(2, 2), mar = 0.1 + c(4, 4, 1, 1), oma = c(0, 0, 2, 0))
for (i in seq(4)) {
  plot(as.formula(form[i]),
    data = anscombe, col = hcl.colors(11),
    pch = 19, cex = 1.2,
    xlim = c(3, 19), ylim = c(3, 13),
    xlab = as.expression(substitute(x[i], list(i = i))),
    ylab = as.expression(substitute(y[i], list(i = i)))
  )
  abline(fit[[i]], col = "red", lwd = 2)
}
mtext("Anscombe's 4 Regression data sets", outer = TRUE, cex = 1.5)
par(op)

2.3 插入表格

一张表格，表格的位置默认居中：

| 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  |

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

Pandoc 支持插入可以跨行的表格，就是一个 cell 里可以跨行，但是 Hugo 不支持。

-------------------------------------------------------------
 Centered   Default           Right Left
  Header    Aligned         Aligned Aligned
----------- ------- --------------- -------------------------
   First    row                12.0 Example of a row that
                                    spans multiple lines.

  Second    row                 5.0 Here's another one. Note
                                    the blank line between
                                    rows.
-------------------------------------------------------------

Table: Here's the caption. It, too, may span
multiple lines.

Here’s the caption. It, too, may span multiple lines.
Centered Header	Default Aligned	Right Aligned	Left Aligned
First	row	12.0	Example of a row that spans multiple lines.
Second	row	5.0	Here’s another one. Note the blank line between rows.

类似地，Hugo 不支持插入 grid 表格，但是 Pandoc 支持。

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+===============+===============+====================+
| Bananas       | $1.34         | - built-in wrapper |
|               |               | - bright color     |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+---------------+---------------+--------------------+

Fruit	Price	Advantages
Bananas	$1.34	built-in wrapper bright color
Oranges	$2.10	cures scurvy tasty

2.4 插入图片

插入一张图片，hugo-xmag 主题的 CSS 样式已经将其设置为自动居中：

Happy Elmo

![Happy Elmo](https://slides.yihui.name/gif/happy-elmo.gif)

看起来好吗？

插入矢量图片是一样的

r-logo

![r-logo](https://cloud.r-project.org/Rlogo.svg)

太大了是不是，我们还可以控制插入的大小

<img width="256" height="256" src="https://cloud.r-project.org/Rlogo.svg">
# 或者
<img width="50%" src="https://cloud.r-project.org/Rlogo.svg">

在 Pandoc 中更加简洁

![r-logo](https://cloud.r-project.org/Rlogo.svg){ width=50% }

r-logo

Pandoc 还支持插入全宽图形，并且交叉引用 \@ref(fig:r-logo)

![(\#fig:r-logo) 一幅全宽的图片](https://www.r-project.org/logo/Rlogo.png){.full}

图 1: 一幅全宽的图片

2.5 插入音频

<iframe frameborder="0" marginwidth="0" marginheight="0" width=400 height=80 src="https://music.163.com/outchain/player?type=2&id=34341360&auto=0&height=66"></iframe>

陈慧娴版《千千阙歌》

张国荣版《千千阙歌》

你不觉得天边的晚霞很美吗？只有看着她，我才能坚持向西走。 — 《悟空传》

戴荃的《悟空》

霍尊的《卷珠帘》

更多可以播放的音乐，去网站搜索 https://music.liuzhijin.cn/

2.6 插入视频

Statistics Views 对 Trevor Hastie 的采访

It’s just serendipity that I ended up in statistics.

统计之都海外沙龙第8期：陈天奇、何通、邱怡轩在聊 xgboost 统计软件奖背后的故事

统计之都海外沙龙第26期：在谷歌、微软、Facebook 搬砖之感受

北京出租车的运行轨迹

2.7 插入幻灯片

Ryan Hafen 在介绍 geofacet

knitr::include_url(url = "https://slides.com/hafen/trelliscopejs-lightning/embed", height = "500px")

Ryan Hafen 在介绍 trelliscopejs

除了从网站插入幻灯片，还支持直接插入 xaringan 制作的幻灯片，下面是我在2019年中国R语言大会（北京）上的幻灯片，也是创建本博客的技术栈。blogdown 出来已经有两年了，很多人使用它创建了自己的博客，统计之都主站是最早使用这套工具的，这次分享以现场操作为主。

2.8 插入列表

定义类型的列表

Cat
: Fluffy animal everyone likes

Internet
: Vector of transmission for pictures of cats

Cat: Fluffy animal everyone likes
Internet: Vector of transmission for pictures of cats

插入无序列表

* one
* two
* three

one
two
three

插入有序的列表

1.  one
2.  two
3.  three

one
two
three

把前面的数字全部换成 1 也是可以的

1.  one
1.  two
1.  three

one
two
three

在列表中含有段落

First paragraph.

Continued.
Second paragraph. With a code block, which must be indented eight spaces:
```
{ code }
```
First paragraph.

Continued.

还可以在列表环境中插入图片

-   One

-   Two

     ![deploy-to-netlify](https://www.netlify.com/img/deploy/button.svg)

-   Three

One
Two

deploy-to-netlify
Three

插入多层的列表， Pandoc 支持多层，而 Hugo 支持两层

* fruits
  + apples
    - macintosh
    - red delicious
  + pears
  + peaches
* vegetables
  + broccoli
  + chard

fruits
- apples
  - macintosh
  - red delicious
- pears
- peaches
vegetables
- broccoli
- chard

2.9 插入脚注

这是内联形式的脚注，对于包含很长内容的脚注，我们建议使用文本引用的方式插入

Here is an inline note.^[Inlines notes are easier to write, since
you don't have to pick an identifier and move down to type the
note.]

Here is an inline note.⁵

采用文本交叉引用的方式，插入脚注

This is a footnote.[^1]

[^1]: the footnote text.

This is a footnote.⁶

脚注中包含段落只在 Pandoc 中支持， Hugo 中不支持

Here is a footnote reference,[^2] and another.[^longnote]

[^2]: Here is the footnote.

[^longnote]: Here's one with multiple blocks.

    Subsequent paragraphs are indented to show that they
belong to the previous footnote.

        { some.code }

    The whole paragraph can be indented, or just the first
    line.  In this way, multi-paragraph footnotes work like
    multi-paragraph list items.

This paragraph won't be part of the note, because it
isn't indented.

3. 参考文献

Markdown https://daringfireball.net/projects/markdown/
Github’s Markdown https://guides.github.com/features/mastering-markdown/
Pandoc’s Markdown https://pandoc.org/MANUAL.html#pandocs-markdown
Hugo’s Markdown https://github.com/russross/blackfriday#features
插入音视频 https://www.sunyazhou.com/2017/12/27/20171227markdown-audio/
非常全面的 Markdown 入门参考 http://xianbai.me/learn-md

我讨厌 CSDN 知乎，支持个人博客，下面是一些我写这篇文章遇到的个人博客

Yifan 一名在帝都的软件工程师，~~对前端非常感兴趣~~ 现在专注于后端服务
AomanHao 热爱图像处理，图像优化世界 matlab
GcsSloop 一名来自2.5次元的魔法师 Java Android
屈光宇专注 WEB 端开发

本博客托管平台的设置类似博文 — Hexo 个人博客迁移到托管平台 Netlify，补充一点，在自定义域名后，添加 SSL/TLS 认证⁷，只需在 Git Bash 中输入

curl -s -v https://xiangyunhuang.com.cn 2>&1 | grep Server

我知道很多人是不会耐着性子把原来的英文文档看完，所以翻译了一下。此外，更新原博文中的一点， Markdown 的任务列表，在较新版本的 Pandoc 2.6 及以上也支持了 https://github.com/jgm/pandoc/releases/tag/2.6。↩︎
Pandoc 2.6 及以上支持任务列表 https://pandoc.org/MANUAL.html#definition-lists ↩︎
这是因为我们必须保护数学表达式，防止被 Markdown 解释。如果你的数学表达式中不包含任何特殊的 Markdown 语法，如下划线或星号，你也许不需要反引号，但更安全的方式是始终添加反引号。↩︎
你肯定会对这里的文本感到无聊↩︎
Inlines notes are easier to write, since you don’t have to pick an identifier and move down to type the note.↩︎
the footnote text.↩︎
https://www.netlify.com/docs/ssl/#troubleshooting ↩︎

Hugo 和 Pandoc 对 Markdown 的扩展支持

黄湘云