Markdown 技巧

使用 R Markdown

常用的 GitHub Flavored Markdown 功能很少，熟悉之后可以使用更强大的 R Markdown。

R Markdown 的优势：

多用途
R Markdown 可以用来写文档，输出格式为 PDF、HTML、Word 等，写书可以用 bookdown。除了写文档，R Markdown 还可以用来写幻灯片（ioslides、Slidy、Beamer、Powerpoint、xaringan 等）和写博客（blogdown）。
可运行代码
R Markdown 中可以插入代码，编译文档后代码结果会在输出文档里面。这样的话，改了代码新的结果也会自动插入到输出文档，就不用自己手动插入图片了。

有序列表只有第 1 个数字有作用

下面的有序列表显示效果一样

1
2
3
1. 香蕉
2. 葡萄
3. 菠萝

1
2
3
1. 香蕉
1. 葡萄
1. 菠萝

1
2
3
1. 香蕉
111. 葡萄
10. 菠萝

它们都会显示为

香蕉
葡萄
菠萝

另外，列表数字可以不以 1 为开头。比如

1
2
3
2. 香蕉
2. 葡萄
2. 菠萝

会显示为

香蕉
葡萄
菠萝

在有序列表中使用同一个数字有两个好处：一是不需要自己手动编号、二是使用 Git 管理文件时变动更少。

图片 + 超链接

超链接的语法是[链接文本](链接网址)，图片的语法是![图片标题](图片网址)。把图片当成超链接的文本，放到超链接的语句中就可以生成带有超链接的图片，也就是[![图片标题](图片网址)](链接网址)。

这是 GitHub 的吉祥物 Octocat

![octocat](https://octodex.github.com/images/kimonotocat.png)

octocat

这是 Github 的链接

[GitHub](https://github.com/)

把它们拼凑起来就可以制作带有 GitHub 链接的 Octocat

[![octocat](https://octodex.github.com/images/kimonotocat.png)](https://github.com/)

因为本站使用了 fancybox，所以点击上面的图片不会跳转到 GitHub。不过你可以把代码复制到 Markdown 编辑器试试看。

使用包含 ``` 的代码块

如果代码块里包含 N 个 `，在需要代码块前后使用 N+1 个 ` 把它包裹起来，不然就会显示错误。下面内容会显示为两个空代码块夹着 print("Hello, World!")。

1
2
3
4
5
```
```
print("Hello, World!")
```
```

上面代码的正确写法应该是

1
2
3
4
5
````
```
print("Hello, World!")
```
````

它会显示为

1
2
3
```
print("Hello, World!")
```

用空行隔开不同元素

用空行隔开不同元素可以消除歧义，避免错误的显示效果。如果不用空行的话，可能会出现意料之外的显示效果。如果我用下面的写法列举我喜欢吃的食物，猜猜 Markdown 编辑器会如何显示。

1
2
3
4
5
6
7
8
水果：
1. 椰子
2. 香蕉
3. 菠萝
烧腊：
1. 叉烧
2. 烧鸭
3. 白切鸡

点击这里查看不同解析器的结果，有三种显示效果。

food

现在你应该知道不加空行的严重后果了。我们再来看看那个错误示范。

1
2
3
4
5
6
7
8
水果：
1. 椰子
2. 香蕉
3. 菠萝
烧腊：
1. 叉烧
2. 烧鸭
3. 白切鸡

它应该包含了 4 个元素：依次为段落、有序列表、段落、有序列表。在元素间加上空行显示就没问题了。点击这里查看效果，这次所有解析结果都正常。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
水果：

1. 椰子
2. 香蕉
3. 菠萝

烧腊：

1. 叉烧
2. 烧鸭
3. 白切鸡

Typora 标题自动标号

typora auto number headings

给 Typora 文章、目录和大纲的标题编号：

按下 Ctrl + ,打开 Typora 设置
点击 Appearance -> Open Theme Folder来打开主题文件夹
Linux 的路径为 ~/.config/Typora/themes
Windows 的路径为 %APPDATA%\Typora\themes

新建一个名为 base.user.css 的文件，把下面的代码粘贴进去（出处）

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
/**************************************
 * Header Counters in Article
 **************************************/

/** initialize css counter */
#write {
    counter-reset: h1
}

h1 {
    counter-reset: h2
}

h2 {
    counter-reset: h3
}

h3 {
    counter-reset: h4
}

h4 {
    counter-reset: h5
}

h5 {
    counter-reset: h6
}

/** put counter result into headings */
#write h1:before {
    counter-increment: h1;
    content: counter(h1) ". "
}

#write h2:before {
    counter-increment: h2;
    content: counter(h1) "." counter(h2) ". "
}

#write h3:before,
h3.md-focus.md-heading:before /** override the default style for focused headings */ {
    counter-increment: h3;
    content: counter(h1) "." counter(h2) "." counter(h3) ". "
}

#write h4:before,
h4.md-focus.md-heading:before {
    counter-increment: h4;
    content: counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) ". "
}

#write h5:before,
h5.md-focus.md-heading:before {
    counter-increment: h5;
    content: counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) ". "
}

#write h6:before,
h6.md-focus.md-heading:before {
    counter-increment: h6;
    content: counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) "." counter(h6) ". "
}

/** override the default style for focused headings */
#write>h3.md-focus:before,
#write>h4.md-focus:before,
#write>h5.md-focus:before,
#write>h6.md-focus:before,
h3.md-focus:before,
h4.md-focus:before,
h5.md-focus:before,
h6.md-focus:before {
    color: inherit;
    border: inherit;
    border-radius: inherit;
    position: inherit;
    left:initial;
    float: none;
    top:initial;
    font-size: inherit;
    padding-left: inherit;
    padding-right: inherit;
    vertical-align: inherit;
    font-weight: inherit;
    line-height: inherit;
}

/**************************************
 * Header Counters in TOC
 **************************************/

/* No link underlines in TOC */
.md-toc-inner {
    text-decoration: none;
}

.md-toc-content {
    counter-reset: h1toc
}

.md-toc-h1 {
    margin-left: 0;
    font-size: 1.5rem;
    counter-reset: h2toc
}

.md-toc-h2 {
    font-size: 1.1rem;
    margin-left: 2rem;
    counter-reset: h3toc
}

.md-toc-h3 {
    margin-left: 3rem;
    font-size: .9rem;
    counter-reset: h4toc
}

.md-toc-h4 {
    margin-left: 4rem;
    font-size: .85rem;
    counter-reset: h5toc
}

.md-toc-h5 {
    margin-left: 5rem;
    font-size: .8rem;
    counter-reset: h6toc
}

.md-toc-h6 {
    margin-left: 6rem;
    font-size: .75rem;
}

.md-toc-h1:before {
    color: black;
    counter-increment: h1toc;
    content: counter(h1toc) ". "
}

.md-toc-h1 .md-toc-inner {
    margin-left: 0;
}

.md-toc-h2:before {
    color: black;
    counter-increment: h2toc;
    content: counter(h1toc) ". " counter(h2toc) ". "
}

.md-toc-h2 .md-toc-inner {
    margin-left: 0;
}

.md-toc-h3:before {
    color: black;
    counter-increment: h3toc;
    content: counter(h1toc) ". " counter(h2toc) ". " counter(h3toc) ". "
}

.md-toc-h3 .md-toc-inner {
    margin-left: 0;
}

.md-toc-h4:before {
    color: black;
    counter-increment: h4toc;
    content: counter(h1toc) ". " counter(h2toc) ". " counter(h3toc) ". " counter(h4toc) ". "
}

.md-toc-h4 .md-toc-inner {
    margin-left: 0;
}

.md-toc-h5:before {
    color: black;
    counter-increment: h5toc;
    content: counter(h1toc) ". " counter(h2toc) ". " counter(h3toc) ". " counter(h4toc) ". " counter(h5toc) ". "
}

.md-toc-h5 .md-toc-inner {
    margin-left: 0;
}

.md-toc-h6:before {
    color: black;
    counter-increment: h6toc;
    content: counter(h1toc) ". " counter(h2toc) ". " counter(h3toc) ". " counter(h4toc) ". " counter(h5toc) ". " counter(h6toc) ". "
}

.md-toc-h6 .md-toc-inner {
    margin-left: 0;
}

/**************************************
 * Header Counters in Content
 **************************************/

/** initialize css counter */
#write {
    counter-reset: h1
}

h1 {
    counter-reset: h2
}

h2 {
    counter-reset: h3
}

h3 {
    counter-reset: h4
}

h4 {
    counter-reset: h5
}

h5 {
    counter-reset: h6
}

/** put counter result into headings */
#write h1:before {
    counter-increment: h1;
    content: counter(h1) ". "
}

#write h2:before {
    counter-increment: h2;
    content: counter(h1) "." counter(h2) ". "
}

#write h3:before, h3.md-focus.md-heading:before { /*override the default style for focused headings */
    counter-increment: h3;
    content: counter(h1) "." counter(h2) "." counter(h3) ". "
}

#write h4:before, h4.md-focus.md-heading:before {
    counter-increment: h4;
    content: counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) ". "
}

#write h5:before, h5.md-focus.md-heading:before {
    counter-increment: h5;
    content: counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) ". "
}

#write h6:before, h6.md-focus.md-heading:before {
    counter-increment: h6;
    content: counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) "." counter(h6) ". "
}

/** override the default style for focused headings */
#write>h3.md-focus:before, #write>h4.md-focus:before, #write>h5.md-focus:before, #write>h6.md-focus:before, h3.md-focus:before, h4.md-focus:before, h5.md-focus:before, h6.md-focus:before {
    color: inherit;
    border: inherit;
    border-radius: inherit;
    position: inherit;
    left: initial;
    float: none;
    top: initial;
    font-size: inherit;
    padding-left: inherit;
    padding-right: inherit;
    vertical-align: inherit;
    font-weight: inherit;
    line-height: inherit;
}

/**************************************
 * Header Counters in Sidebar
 **************************************/

.sidebar-content {
    counter-reset: h1
}

.outline-h1 {
    counter-reset: h2
}

.outline-h2 {
    counter-reset: h3
}

.outline-h3 {
    counter-reset: h4
}

.outline-h4 {
    counter-reset: h5
}

.outline-h5 {
    counter-reset: h6
}

.outline-h1>.outline-item>.outline-label:before {
    counter-increment: h1;
    content: counter(h1) ". "
}

.outline-h2>.outline-item>.outline-label:before {
    counter-increment: h2;
    content: counter(h1) "." counter(h2) ". "
}

.outline-h3>.outline-item>.outline-label:before {
    counter-increment: h3;
    content: counter(h1) "." counter(h2) "." counter(h3) ". "
}

.outline-h4>.outline-item>.outline-label:before {
    counter-increment: h4;
    content: counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) ". "
}

.outline-h5>.outline-item>.outline-label:before {
    counter-increment: h5;
    content: counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) ". "
}

.outline-h6>.outline-item>.outline-label:before {
    counter-increment: h6;
    content: counter(h1) "." counter(h2) "." counter(h3) "." counter(h4) "." counter(h5) "." counter(h6) ". "
}

保存文件并重启 Typora

为什么 Markdown 的标题叫 ATX 和 Setext

Markdown 有两种标题写法，一种是 ATX 标题（ATX headings）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# foo

## foo

### foo

#### foo

##### foo

###### foo

另一种是 Setext 标题（Setext Headings）：

1
2
3
4
5
Title 
=====

Subhead 
-------

有很长一段时间，我都没法区分哪种标题是 ATX，哪种是 Setext。我特地用词典查 ATX 和 Setext，根本查不到释义。最近在谷歌和维基百科的帮助下，才发现原来这两个标题写法不是 Markdown 原创的，是出自 atx(the true structured text format) 和 Setext (Structure Enhanced Text)。

避免使用其他标记语言

Markdown 的格式有限，要使用 Markdown 不支持格式，就只能混用其他标记语言。但是混用标记语言可能会让你陷入追求格式的泥潭。举个例子，Markdown 不支持右对齐，要对文字右对齐只能使用 HTML 代码，比如 <div style="text-align: right">右对齐的文字</div>。这么做有两个问题，一是要输入长长的代码，二是转换成 HTML 以外的文档（如 PDF）右对齐代码就失效了。下面这个 Markdown 文件转换成 PDF 的话，右对齐会失效。

1
2
3
4
5
> 春有百花秋有月，夏有凉风冬有雪。
>
> 若无闲事挂心头，便是人间好时节。
>
> <div style="text-align: right">——无门慧开</div>

春有百花秋有月，夏有凉风冬有雪。
若无闲事挂心头，便是人间好时节。
——无门慧开

其实在 R Markdown 中有让右对齐代码同时对 HTML 与 PDF 生效的方法（参考资料：9.6 Custom blocks (*) | R Markdown Cookbook）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
---
output:
  pdf_document: default
  html_document: default
---

<style>
.flushright {
  text-align: right;
}
</style>

> If your mind isn’t clouded by unnecessary things,
>
> This is the best season of your life.
>
> ::: {.flushright data-latex=""}
> --- Wu-Men
> :::

在 R Markdown 中加载 LaTeX 宏包

extra_dependencies

1
2
3
4
5
---
output: 
  pdf_document:
    extra_dependencies: ["bbm", "threeparttable"]
---

1
2
3
4
5
6
7
8
---
output: 
  pdf_document:
    extra_dependencies:
      caption: ["labelfont={bf}"]
      hyperref: ["unicode=true", "breaklinks=true"]
      lmodern: null
---

header-includes

1
2
3
4
5
6
---
header-includes:
   - \usepackage{bbm}
output:
    pdf_document
---

in-header

1
2
3
4
5
6
---
output:
    pdf_document:
        includes:
            in_header: mystyles.sty
---

1
2
3
4
5
% mystyles.sty
\usepackage{bbm}
\usepackage{threeparttable}
\usepackage{booktabs}
\usepackage{expex}

文章目录