叶寻的博客

Markdown 技巧

叶寻
目次

使用 R Markdown #

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

R Markdown 的优势：

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

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

1
2
3

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

1
2
3

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

1
2
3

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

它们都会显示为

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

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

1
2
3

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

会显示为

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

在有序列表中使用同一个数字有两个好处：一是不需要自己手动编号、二是使用 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/)

octocat

如果点击上面的图片不会跳转到 GitHub，可能是因为本站使用了 PhotoSwipe 这样的相册插件。你可以把代码复制到 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. 白切鸡

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

第 1 种显示效果
第 2 种显示效果
第 3 种显示效果

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

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 自动标号的截图

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

参考资料 #

标签：
comments powered by Disqus