小叶的 Markdown 简明教程

发表于 分类于 ， 本文字数： 3k 阅读时长 ≈ 11 分钟
这是一篇，立志让草履虫也能明白的 Markdown 简明教程。

关于本教程

出于「优雅且唯一」的小叶之禅，本文仅选择性地介绍 Markdown 诸多方言（dialect）中最简单最流行的一种。

简介

Markdown 作为一款轻量标记语言，受到广大文字工作者的欢迎。其语法流行于各大社交平台和笔记软件，为用户的内容输出提供了更加优美的格式支持。它通过简单的格式标记，将人从排版软件繁琐的格式控制中解放出来，从而专心于内容创作。

Markdown 文档本质上和 TXT 文本文档没有任何区别，你可以新建文本文档并修改后缀为 .md 来创建空白 Markdown 文档。正因为其本身为纯文本内容，Markdown 不对渲染样式作任何保证，因此，选择合适的编辑器是输出精致美观的文档的关键。

编辑器

Visual Studio Code

出于版本管理字符控制等诸多原因，小叶写作时主要使用 Visual Studio Code。该编辑器并非开箱即用，对于没有任何代码经验的文字工作者们并不友好。

Typora

Typora 是目前最受欢迎的 Markdown 编辑器。它支持实时渲染，所见即所得，无需 掌握 Markdown 语法即可上手。推荐通过其 源码模式 观察学习 Markdown 语法。

Typora 自正式版本退出以后变为付费软件，但并未下架其免费版本。Typora 的最后一个免费版本为 0.11.18，其下载地址如下：

呼呼！小叶用的自然是十五美刀的正式版。

语法

首先，我们先完全抛弃 Microsoft Word 灌输的章、节、分栏、分页等等复杂概念，它们与计算机领域的简洁无关。Word（及同类软件）应视作 排版软件 而非 写作软件，它是用于对格式的精确控制的。即使你有更复杂的格式要求，也应该首先完成内容创作，然后统一复制到 Word 里调整格式。

当然，专业的排版应更多地考虑使用 LaTeX。

请格外注意，Markdown 中承担语义的所有符号皆为 半角。

转义

使用 \ 取消 Markdown 特殊符号语义。

正文

什么是行？

行是一个源码层面的概念。

输入文字时，由于页面宽度不够产生的自动换行，称为 自动折行。由自动折行导致的多行文本，在计算机领域中视为同一行。

那么什么是行呢？简单来说，你敲一下回车（ENTER 或者 RETURN）即是一行。敲回车的动作称为 换行。

查看更多

在不同的操作系统下，行的定义因 换行符（EOL）的选择而略有不同。Linux 和 macOS（OS X）使用 \n（LF）作为一行的结束；Windows 则使用 \r\n（CRLF）；早期的 macOS 甚至为 \r（CR）。这导致了一系列的麻烦，此处按下不表。

好在 Typora 可以选择换行符。请永远选择 LF！

小叶的历史小故事

LF 与 CRLF 之争要追溯到机械打字机时代。CR 指回车（Carriage Return），即打字头从滑杆右端返回左端；LF 指换行（Line Feed），即纸张上移，使打字头对准新的一行。从历史渊源上讲，回车换行（CRLF）才是一次换行的完整过程。但计算机毕竟没有打字机的机械结构，为了节省字符，多数系统采用了 LF 作为换行符，苹果独树一帜，莫名其妙地使用了 CR 作为换行符，还好浪子回头，和主流保持了一致。微软嘛，情怀也好、搞特殊也罢，它产生的麻烦已经够多了。

什么是段落

段落是一个渲染层面的概念。

在 Markdown 源码中，连续两次换行（表现为多出一个空行）产生一个段落，对应 Word 中的 硬换行。

1
2
3
4
5
这是一个段落。

这是另一个段落。

这又是一个段落。根据某个古老的传统，请在任何文档的结尾新增一个空行。不能多，也不能少，否则蠢蠢欲动的格式警察和蛮荒年代的字节流粘连将会把你吞没！

那么什么是软换行呢？

在 Word 中，软换行指：同属一个段落的两行文字，即使页面宽度足够，也被分成两行的行为。使用 SHIFT + ENTER 可以在 Word 文档里插入一个软换行。

Typora 将 Markdown 源码里敲的一个回车视作一次软换行，于是异端在此间滋生: 同样是没有空行的两行文本，GitHub 会渲染成空格分隔的两句话。即，软换行行为是没有保证的，了解就好，不要使用，最好忘掉。

标题

使用 # 标题文本 表示标题。

最低一级标题为六个连续 # 标记的六级标题，更多的 # 会使该行失去语义。

1
2
3
4
5
6
7
8
9
10
11
# 这是一个一级标题

## 这是一个二级标题

### 这是一个三级标题

#### 这是一个四级标题

##### 这是一个五级标题

###### 这是一个六级标题

风格指南

原则上，一份文档（不仅仅只是 Markdown 文档）中：

  • 有且仅有一个一级标题；
  • 标题的层级应当连续；
  • 不得使用标题语义来放大正文文本，而应当为其单独定义样式。

在 Markdown 中，标题是方言最多的部分（大概）,此处不做介绍。拒绝异端，从我做起。

引用

使用 > 文本 表示引用。

与正文类似，文本行之间应当空行，使用 > 表示引用文本的空行。

1
2
3
4
5
6
7
8
9
> 这是一段引用文本。
>
> 下面是嵌套的引用文本：
>
> > 回忆是一件危险的事情，处处布满了恫吓与陷阱。我不该这么想，我仍然这么想：
> >
> > 倘若永不开场，天下也有不散的宴席。
>
> 上面是嵌套的引用文本。

列表

使用 - 文本 表示无序列表的一项。

使用 数字. 文本 表示有序列表的一项。建议永远使用 1. 文本 表示有序列表，渲染结果将自动编号。

使用 - [ ] 文本 表示任务列表的未完成项。

使用 - [x] 文本 表示任务列表的完成项。

使用新增四个空格缩进的列表项表示父列表的子项，不同种类的列表可以嵌套。

列表项之间一般不空行，扩大间距可空出一行。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
- 这是无序列表的一项。
- 这是无序列表的另一项。
- 这又是无序列表的一项。

1. 这是第一项。
1. 这是第二项。
1. 这是第三项。

- [ ] 这是未完成项。
- [x] 这是完成项。

- 这是父列表。
    1. 这是嵌套子列表。
    1. 这是嵌套子列表。
        - [ ] 这是嵌套子列表。
        - [x] 这是嵌套子列表。
- 这是父列表。
    - 这是嵌套子列表。
    1. 这是嵌套子列表。
    - [x] 这是嵌套子列表。
- 这是父列表。

文本样式

1
2
3
4
5
*斜体 Italic*

**加粗 Bold**

~~删除 Strikethrough~~

当且仅当斜体和加粗混排时，使用下划线 _ 代替其中一种文本样式的星号 *。

链接

使用 [显示文本](链接) 表示链接。此处链接可以是网址，也可以是本机文件地址。记笔记时，可以通过相对链接将各个笔记文档关联起来，形成网络。在 Obsidian 里，你可以通过双向链接将知识网络可视化的表现出来。

使用 [显示文本](#章节) 表示章节链接。章节即指各级标题，值得注意的是，章节链接仅通过标题文本来进行定位，而不会考虑其层级。同名章节存在时，它会定位到第一次出现的位置。

使用 [显示文本](文章链接#章节) 定位其他文章中的章节。

使用 <链接> 直接显示链接地址。

参考链接和脚注略。

图片

使用 ![替代文本](图片地址) 插入图片。

替代文本为可选内容，可以为空；

图片地址可以是网址，也可以是本机图片的文件地址。

水平分割线

为了与 Front-Matter 区分，使用 6 个单独成行的 - 表示水平分割线。

代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
## 行内代码

代码 `print('I love you.')` 可以将 “I love you” 写入标准输出。

## 多行代码

```
While True:
    print('I love you.')
```

标注代码语言可实现语法高亮。

```Python
While True:
    print('I love you.')
```

公式

公式的语法是 LaTeX 的一个子集。

1
2
3
4
5
6
7
8
9
10
11
12
13
## 行内公式

欧拉恒等式 $\mathrm{e}^{\mathrm{i}\pi} + 1 = 0$ 即欧拉公式中 $x = \pi$ 的情形。

## 多行公式

$$
\begin{align}
\mathrm{e}^{\mathrm{i}x} &= \cos{x} + \mathrm{i}\sin{x}\quad let\ x = \pi \\
\mathrm{e}^{\mathrm{i}\pi} &= \cos{\pi} + \mathrm{i}\sin{\pi} \\
\mathrm{e}^{\mathrm{i}\pi} &= -1 + 0 \\
\end{align}
$$

HTML 标签

Markdown 原生支持 HTML，但是，从简单轻量的原则出发，请尽量不要使用 HTML，因为 Markdown 不应用于复杂格式的输出。

此外，由于解析器的不同，出于兼容性考虑，请不要在 HTML 标签内插入空行，更不要继续使用 Markdown 原生语法。

Front-Matter

Markdown 的文档开头可以插入 YAML 或 JSON 序列化字符串以标注文档元信息（如果你不懂什么是 YAML 和 JSON，那么你也没有任何必要使用 Front-Matter）。其中，关于 JSON 的语法较为丑陋，以下只讨论 YAML。

文件首行 单独插入 3 个 - 然后使用 YAML 语法，并在语句块结束以后另起一行再次插入 3 个 - 以包裹语句块，即构成了 Markdown 文档的 Front-Matter。

一个有趣的事实是：由于 YAML 使用 # 注释，Markdown 使用 HTML 风格的 <!-- comment --> 注释,当你跨域连续使用 CTRL + / 注释时，会发生一些意想不到的结果（至少在 Visual Studio Code 如此）。

更多

Markdown 还支持表格、流程图等等内容，我确信已想到了一种美妙的展示方法，可惜这里空白太小，写不下。

有点麻烦。有点麻烦的事情，还是交给 Typora 辅助生成吧。

导出

直接导出 .png 图片的图片质量有限，一个更佳的实现是：

  1. 导出带样式的 HTML 文档；
  2. 使用 Chrome 打开；
  3. 在 Chrome 中按下 F12 进入开发者模式；
  4. 选择左上角 “Toggle device tool bar”；
  5. 点击省略号菜单中的 “Capture full size screenshot” 选项并保存到本地。

兼容性

Markdown 的原生语法相当有限，随着人们对格式的进一步要求，Markdown 诞生了一系列扩展语法以及方言，而这些扩展语法和方言的可用性并不总是能够得到保证。据我所知，任务列表、代码、公式、流程图等扩展语法中，只有代码几乎被所有的平台支持，而公式的支持则较为有限，随着渲染引擎的不同（比如，相比 MathJax，KaTeX 只能处理 LaTeX 数学符号的更小子集），部分公式的渲染结果可能不一致。

如此如此，这般这般，对于兼容性的问题，其实不必过多的担心。本文列举的语法完全兼容 Typora 和 GitHub 平台，更复杂的需求，你应该尝试内嵌 HTML。