Markdown 标记语言指北

这是班刊约稿的一篇文章.

全文约6000字, 预计需要 60 分钟读完.

Markdown 标记语言指北

TOC

1. 什么是 Markdown?
2. Markdown 可以用来干什么?
3. 第一步?
4. 一些专业一点的内容
5. Markdown 的简要语法
6. GFM?
7. 段落
8. 标题
9. 文字的修饰
10. 段落的修饰
11. 列表
12. 插入
    
    1. 超链接
    
    2. 图片
13. 表格
14. 进阶的应用
    1. 数学公式
    2. 代码
    3. 嵌入HTML
    4. 扩展的 Markdown
15. 总结
16. 后记
17. 关于
18. Reference

Abstract

Markdown\(^1\) 创造于 2004 年, 是网络上最常用的用于编写文档的语言之一. 这篇文章作为一篇指南, 简要介绍了 Markdown 标记语言的语法和原理, 以及利用它撰写文档的一些实践. 同时, 本文也涉及到一些数学公式排版的内容与 \(\TeX\) 排版引擎的原理.

什么是 Markdown?

9102年了, 你还在用 Microsoft Word 写文档吗? (大雾)

毫无疑问, MS Word 是这个星球上通用性最强, 功能最强大的文字处理软件. 秉承着所见即所得\(^2\) (What You See Is What You Get, WYSIWYG) 的精神, 它提供了一流的写作与排版体验.

但是, 用 MS Word 编写所有文档可能并不是一个好的选择. 比如说:

• 你想写一个小文档, 打开了笨重达 2GB 的 MS Word
• 你想写一个文档, 然后一边写一边 (凭感觉) 排版, 甚至打乱了你的节奏
• MS Word 有沉重的兼容性包袱. 同一份 doc 文档在不同的 MS Word 版本上显示效果往往会有不同, 更不用说 WPS 了
• 在很多地方并不支持 doc 和 docx 格式, 或者支持较弱. 比如 Linux, Mac OS, 笔记应用, 以及绝大部分网站
• MS Word 是付费软件. 你要不就付出每年至少 \(99\) 刀的 Office 365 授权费用, 要不就忍受使用盗版. (事实上, 这并不是一个小问题)

Office 365 ProPlus

那么, 你还有 Markdown.

根据所见即所想\(^3\) (What You See Is What You Mean, WYSIWYM) 的理念, 我在这里推荐一种让你无需考虑排版, 轻量级, 纯文本格式, 但能让你快速写出十分美观的文档的标记语言. 它就是 Markdown.

-------------------------废话预警-------------------------

什么是标记语言呢?

据 Wikipedia\(^4\) , 标记语言是一种将文本以及文本相关的其他信息结合起来的文字编码.

比如说, 下面这段 Markdown:

- 尼采说：
    > Was mich nicht umbringt, macht mich **stärker**.

会被翻译成:

---

• 尼采说：

  Was mich nicht umbringt, macht mich stärker.

---

翻译的过程由处理引擎帮你处理 (这被称为渲染), 你只需在文字处打上对应的标记 (比如上文的 -, **...**) 即可.

这无疑为文字排版带来了极大的方便.

-------------------------废话预警结束-------------------------

简单的说, Markdown 通过一系列控制字符, 使得写作本身和排版的细节分离, 并且轻量化, 易读写.

分离写作和排版还会带来一个意想不到的好处: 你可以轻松地, 迅速地把文档转换成另一个主题, 或者另一个样式.

在大多数 Markdown 编辑器中, 你只需要点几下鼠标, 修改一下设置, 就能做到这一点. 后面就有 Typora 编辑器使用不同主题的效果 ~

Markdown 可以用来干什么?

作为一种为写作而生的语言, 它在日常写作方面几乎可以代替 MS Word.

你可以用 Markdown:

• 写文章
• 写书
• 写 Blog
• 写笔记
• 甚至, 写 (数学, 物理, 或者计算机的) 论文

很多知名的网站也支持 Markdown 写作. 比如:

• 简书 (http://www.jianshu.com/)
• 马克飞象, 印象笔记的一款工具
• GitHub, 全球最大的同性(程序员)交友网站
• Reddit, 知名的娱乐、社交及新闻网站
• Stack Exchange, 专业问答社区
• Gitbook, 写作网站

另外, 这篇文章就由 Markdown 写成, 并转换为 PDF 文档.

第一步?

为了编写 Markdown 文档, 你需要一个能够渲染 Markdown 的编辑器.

我在这里推荐 Typora\(^5\) , 一款跨平台的 Markdown 写作软件. 和臃肿的 MS Word 不同, 这个软件的安装包仅有 43MB 大小, 并且具备写作 Markdown 的绝大部分功能. 你可以在 Windows, Mac OS, 甚至各大 Linux 发行版上使用它.

直接在 Typora 的界面就可以写作 Markdown!

Typora 的渲染界面和源代码界面

Typora 的各种主题

(图片中内容来自 善用佳软\(^6\) , CC0协议)

常用的 Markdown 处理工具还包括:

• VS Code + Markdown All in One, 支持实时预览, 同样非常好用
• 简书, 使用 Markdown 的博客网站
• 马克飞象, 用于印象笔记
• Mou, Mac 下十分漂亮的写作软件
• 有道云笔记, 支持 Android, IOS, 网页端

一些专业一点的内容

Markdown 文本是如何渲染的?

事实上, Markdown 实现的东西就是标记式语言 HTML 的一个子集. 也就是说, 所有 Markdown 的标记都可以在 HTML 中找到等价的描述. 利用 Javascript 或者 PHP, 很容易写出一个 Parser, 把 Markdown 翻译成 HTML. 更进一步, 通过修改相关的 CSS 样式表, 也很容易实现主题, 字体的修改. 相关的实现有 MarkedJS\(^7\) , 以及神仙语言 Haskell 实现的 Pandoc\(^8\) 等等.

Markdown 的简要语法

GFM?

Markdown 只是一种大致的规范, 它有很多种具体的标准和扩展. 好在这几种标准之间只是在细节处有所不同. 在这里, 我主要介绍现在应用相对广泛的 Github Flavored Markdown (GFM, Github 口味的 Markdown, 对, 就是那个全球最大的同性交友网站). GFM 在原先的标准 CommonMark 上做了一些扩展, 使得 Markdown 的表达能力更强, 写作更加便利.

下面的叙述难免会遇到空白符. 为了叙述清楚, 我会用 •代替空格, 用 → 代替 Tab (就是键盘第三排左面的那个键), 用 ↓ 表示空行 ~

段落

我们先了解一个核心的概念: 段落.

Markdown 使用一个空行来分段.

为了兼容其他的一些符号, 简单的回车会被当成空格符.

另外, 如果你想在一段中插入多行, 可以在上一行尾加入两个空格.

例如:

空饮狂歌空度日
↓
飞扬跋扈为谁雄
↓
那一双傲慢的靴子至今还落在••
高力士羞愤的手里
人却不见了

会被渲染成:

---

空饮狂歌空度日

飞扬跋扈为谁雄

那一双傲慢的靴子至今还落在

高力士羞愤的手里

人却不见了

---

还记得我说过的所见即所想 (WYSIWYM) 吗?

在 Markdown 中, 你并没有简便的方法去实现一些你原先常用的操作. 比如说: 在两段之间插入三个空行. Markdown 会自动处理换行和行间距, 但你在大多数情况下并不需要连续的两个换行. 类似地, 你也无法在两个单词之间插入好几个空格.

在春天
↓
↓
最后的••••••••一个春天

---

在春天

最后的 一个春天

---

这并不是说禁止你这么干. 你也可以通过嵌入 HTML (<br>) 的方式来实现连续的两个换行. 但是, 这个设计的精髓在于: 你没有必要考虑你的文字的排版细节. Markdown 会做好排版的事情, 而你只需要专注于重要的东西: 你正在写的内容. (这句话其实是 LyX 文档中的, 但无疑也适用于 Markdown)

你可能会想要首行缩进.

实际上 Markdown 也没有这样的设计, 但是你仍然可以利用 HTML: 在行首加一个  . (或许你也会觉得这是没有必要的)

  Hahaha

---

  Hahaha

---

有时候你可能会想要一个比段落更强的分隔. Markdown 提供了分割线, 用来分割两段的内容. 它就形如三个连续的 -, 或者 *, 或者 _. (是不是很形象:P)

其实前面的演示中已经用到分割线了...

---
***
___

---

---

---

标题

在 MS Word 或者其他编辑器中, 你加入一个标题的过程可能是: 输入标题, 选择文字, 用模板或者手动修改样式. 但在 Markdown 中, 你只需要在文字前加入 \(1\) ~ \(6\) 个 #, 就能实现不同层级的标题.

# 一级
## 二级
### 三级
#### 四级QAQ
##### 五级
###### 六级

---

一级

二级

三级

四级QAQ

五级

六级

---

标题还有一种更古老的样式: 在文字下加 ---. 不过它不常用并且不方便, 还不支持三级以上的标题, 在这里就不介绍了.

文字的修饰

Markdown 提供了多种文字的修饰.

• 斜体: *WORD*
• 加粗: **WORD**
• 斜体加粗: ***WORD***
• 删除线: ~~WORD~~

前面三种的 * 也可以用 _ 代替.

*例如*••
**你有五秒钟的时间**••
***来看试卷上的例题***••
~~你将听到以下对话~~••
__Excuse me. Can you tell me how much the shirt is ?__

---

例如

你有五秒钟的时间

来看试卷上的例题

你将听到以下对话

Excuse me. Can you tell me how much the shirt is ?

---

我们已经学习了很多符号了.

你有没有想过这样一个问题: 如果你想在文字中包含这些字符怎么办?

Markdown 提供了一种解决方案: 使用转义字符.

在特殊字符前加 \, 表示对这个字符转义, 也就是保留这个字符不变. 特殊地, 可以用 \\ 来转义 \.

**这是粗体**••
\*\*但这并不是\*\*••
\\*\\* 看看这个,反斜杠变成了斜体 \\*\\*••

---

这是粗体

**但这并不是**

\\ 看看这个,反斜杠变成了斜体 \\

---

这是一个可以转义的字符的列表:

\   反斜线
`   反引号
*   星号
_   底线
{}  花括号 (braces)
[]  方括号 (brackets)
()  括弧
#   井字号
+   加号
-   减号
.   英文句点
!   惊叹号

段落的修饰

有时候你会想引用一段话. 比如一句名言, 诗歌, 或者你自己的一句话.

在 Markdown 中, 你只需要在你想引用的段落前加 > 即可.

另外, 没有用分隔符分开的两段, 在引用中会显示在同一个区块中.

在引用中仍然可以使用很多 Markdown 的标记, 比如标题, (后面要讲的) 列表等等.

林则徐在《赴戍登程口占示家人》中写道：
> 力微任重久神疲，再竭衰庸定不支。苟利国家生死以，岂因祸福避趋之。••
谪居正是君恩厚，养拙刚于戍卒宜。戏与山妻谈故事，试吟断送老头皮。
↓
> 注释：••
> 1. 戍：驻守••
> 1. 口占：即兴作诗，不打草稿，随口吟诵出来••
> 1. 衰庸：意近“衰朽”，衰老而无能，自谦之词••

---

林则徐在《赴戍登程口占示家人》中写道：

力微任重久神疲，再竭衰庸定不支。苟利国家生死以，岂因祸福避趋之。

谪居正是君恩厚，养拙刚于戍卒宜。戏与山妻谈故事，试吟断送老头皮。

注释：

1. 戍：驻守
2. 口占：即兴作诗，不打草稿，随口吟诵出来
3. 衰庸：意近“衰朽”，衰老而无能，自谦之词

---

列表

Markdown 支持有序列表和无序列表.

无序列表把每一行用 -•, *•, 或者 +•开头, 不过不要在一个列表中混用多个符号:

-•hia
-•hiA
-•hIa
*•hIA; 这是另一个列表

---

• hia
• hiA
• hIa

• hIA; 这是另一个列表

---

类似地, 有序列表把每一行用 非负数.•开头, 不过略显复杂:

• 非负数可以有前导 \(0\), 不过没有效果
• 第一个数表示列表第一项的标号, 后面的标号依次递增; 也就是说, 后面的数并不会影响渲染之后的标号
  • 其实全用 1. 就好, 这样就不用关心具体的标号是多少了

1. 这是合法的
4432. 这个标号是 2
00001. 这也是合法的

---

1. 这是合法的
2. 这个标号是 2
3. 这也是合法的

---

Markdown 还支持多级列表.

具体地, 只需在行前加空格, 让列表某一行的标号在列表上一行的文字部分之后, 就可以缩进到二级 (或者更多级) 列表.

Tab 在行首有相同的功效. 事实上, 行首的 Tab 就相当于四个空格.

对我而言, 我更喜欢直接在行首加 Tab, 这样会使无论是源代码还是渲染后的结果都清晰易懂.

表格之间还可以嵌套. 也就是说, 在有序列表的二级列表可以是无序列表, 或者反过来.

类似引用, 在列表里也可以使用 Markdown 的其他元素.

1.•一级
•••1.•二级
••••••1.•三级
12343.•一级
•••1.•但这是一级
••••••1.•二级
→   →   1.•使用 Tab 的二级
1. ##### Lorem!
    - 一个无序列表

---

1.•上面的是演示, 下面的才是正常风格
→   1.•二级
→   →   1.•三级
1.•一级
→   - 一个无序列表

---

1. 一级
   1. 二级
      1. 三级
2. 一级
3. 但这是一级
   1. 二级
   2. 使用Tab的二级

4. Lorem!

---

1. 上面的是演示, 下面的才是正常风格
   1. 二级
      1. 三级
2. 一级

• 一个无序列表

---

插入

Markdown 还支持插入图片和超链接.

超链接

超链接有三种形式.

行内式

形如这样: [an example](http://example.com/ "Title")

• an example 是想显示出的文字
• http://example.com/ 是网站链接, 也可以是本机路径(绝对路径或者相对路径)
• "Title" 是把鼠标放在这个链接上时显示的文本
  • 相信你也发现了这个东西似乎没什么用; 所以, 这部分是可选的