1 Markdown 是什么

  Markdown 是一种用纯文本写格式化文档的写法。

  传统做法是：写完文字，再用鼠标点一堆按钮设标题、加粗、插列表。Markdown 是另一种思路——你直接把这些格式“写”出来：

1
2
3
# 这是一级标题
**这是加粗**
- 这是列表项

  就这么简单。它有几个好处：

  ——纯文本。任何编辑器都能打开，不怕软件过时。
  ——手不离键盘。不用去点工具栏。
  ——通用。GitHub、知乎、语雀、Notion、Obsidian、Typora 全都支持。
  ——能转成别的格式。同一份文档可以输出成 HTML、PDF、Word。

  这篇教程的写法是：每讲一个语法，先给源码，紧接着把渲染效果摆出来。你对照着看，一眼就能明白两者的对应关系。

  半小时能学会常用语法，剩下的边用边查就行。

2 标题

  用 # 表示标题层级，几个 # 就是几级标题。源码：

1
2
3
4
5
6
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

  渲染效果（受页面样式影响，这里只显示文字大小差异）：

一级标题

二级标题

三级标题

四级标题

五级标题
六级标题

  几个注意点：

  ——# 后面要有一个空格，#标题 不生效。
  ——一篇文章通常只用一个一级标题（一般就是文章标题）。正文的小节从二级开始。
  ——别为了“字大一点”乱用层级，标题层级会影响目录结构。
  ——最多六级，七级开始不生效。

  还有一种下划线式的写法，只能用于一二级标题：

1
2
3
4
5
一级标题
========

二级标题
--------

  这种写法现在很少用了，知道有这回事就行。

3 文字样式

  源码：

1
2
3
4
5
6
**粗体**
*斜体*
***粗斜体***
~~删除线~~
`行内代码`
普通文字

  渲染效果：

粗体　斜体　粗斜体　删除线　行内代码　普通文字

  也可以混着用，比如 粗体里有斜体、斜体里有粗体。

  用法上我自己的习惯：

  ——加粗用来强调关键结论、术语、需要一眼看到的东西。
  ——斜体用得少。中文里斜体效果不好看，而且容易和强调混淆；英文里斜体常用来表示书名、术语。
  ——行内代码用来标命令、文件名、变量名、路径。

  关于斜体还有个坑：* 和 _ 都能表示斜体，但 _ 在单词内部不生效（这是为了避免把 snake_case_name 这种变量名当成斜体）：

1
2
_snake_case_name_    会被渲染成斜体吗
my_file_name_here    下划线在词内，不生效

  渲染成：snake_case_name 和 my_file_name_here。所以涉及下划线的代码和变量名，一定用反引号包起来。

4 列表

4.1 无序列表

  源码：

1
2
3
- 苹果
- 香蕉
- 橘子

  渲染效果：

  • 苹果
  • 香蕉
  • 橘子

  也可以用 * 或 +，效果一样：

1
2
* 用星号
+ 用加号
  • 用星号
  • 用加号

  但同一篇里最好统一用 -，看着整齐。

4.2 有序列表

  源码：

1
2
3
1. 第一步
2. 第二步
3. 第三步

  渲染效果：

  1. 第一步
  2. 第二步
  3. 第三步

  有个反直觉的地方：你写的数字其实不重要。下面这样也能正确渲染：

1
2
3
1. 第一步
1. 第二步
1. 第三步
  1. 第一步
  2. 第二步
  3. 第三步

  Markdown 会自动编号。这个特性在插入新条目时很方便——不用手动改后面所有序号。

  但注意起始数字是有意义的：

1
2
5. 从五开始
6. 下一个
  1. 从五开始
  2. 下一个

4.3 嵌套列表

  子项前面加两个空格（或一个 Tab）。源码：

1
2
3
4
5
6
- 第一章
  - 第一节
  - 第二节
- 第二章
  1. 第一条
  2. 第二条

  渲染效果：

  • 第一章
    • 第一节
    • 第二节
  • 第二章
    1. 第一条
    2. 第二条

  缩进量要一致，一会两个空格一会四个空格，很容易渲染错。建议统一用两个空格。

4.4 任务列表

  源码：

1
2
3
- [x] 已经做完的事
- [ ] 还没做的事
- [ ] 另一件没做的事

  渲染效果：

  • [x] 已经做完的事
  • [ ] 还没做的事
  • [ ] 另一件没做的事

  注意 - 和 [ 之间有空格，[x] 里面是小写 x。

5 链接与图片

5.1 行内式链接

  源码：

1
[点我去百度](https://www.baidu.com)

  渲染效果：点我去百度

  还可以给链接加悬停提示：

1
[点我](https://www.baidu.com "这是鼠标悬停时的提示")

  渲染效果：点我（鼠标移上去看看）

5.2 引用式链接

  同一个链接在文中多次出现时，用引用式更清爽。源码：

1
2
3
这是[某个链接][1]，稍后还会提到[某个链接][1]。

[1]: https://www.baidu.com

  渲染效果：这是某个链接，稍后还会提到某个链接。

  好处是链接地址只在文末写一次，正文里很干净。

5.3 自动链接

  用尖括号包住 URL，会直接变成可点的链接：

1
2
<https://www.baidu.com>
<mailto:someone@example.com>

  渲染效果：https://www.baidu.com　mailto:someone@example.com

5.4 图片

  源码：

1
![图片说明](图片地址)

  开头的 ! 是关键，表示这是图片不是链接。方括号里的是替代文本（图片加载失败时显示，也用于无障碍阅读）。

  图片和链接一样，也支持悬停提示：

1
![说明](图片地址 "悬停提示")

  图片路径有两种写法：

  ——绝对路径 /assets/pictures/a.png：从网站根目录算起。换文章位置不用改路径，推荐。
  ——相对路径 ./a.png：从当前文件算起。

  在博客里我一般用绝对路径，因为文章可能在首页、归档页、标签页等多个位置显示，相对路径容易失效。

6 代码

6.1 行内代码

  源码：

1
安装完了敲 `npm install` 就能用。

  渲染效果：安装完了敲 npm install 就能用。

  行内代码里想包含反引号本身，用两个反引号包住：`有反引号的代码`。

6.2 代码块

  用三个反引号包住，后面写上语言名。源码：

1
2
3
4
```python
def hello():
    print("Hello")
```

  渲染效果：

1
2
def hello():
    print("Hello")

  写上语言名（python、javascript、bash、matlab……）才会有语法高亮。不写也能显示，但就是一片灰色：

1
2
3
没有语言名的代码块
def hello():
    print("Hello")

  几个容易忽略的点：

  ——代码块内不需要转义。想显示 # 就直接写 #，不会被当成标题。
  ——代码块里想包含三个反引号，外层就用四个或更多反引号包住（我上面那段示例就是这么写的）。
  ——缩进不要用 Tab。不同工具对 Tab 宽度处理不一样，用空格更保险（一般 2 或 4 个）。

7 引用块

  源码：

1
2
> 这是一段引用。
> 可以写多行。

  渲染效果：

这是一段引用。
可以写多行。

  引用可以嵌套：

1
2
3
4
5
6
> 第一层引用
>
> > 第二层引用
> > 还在第二层
>
> 回到第一层

第一层引用

第二层引用
还在第二层

回到第一层

  引用里也能放其他语法：

1
2
3
4
> **注意**：执行前请先备份。
>
> ```bash
> cp -r data data.bak
1
2
3
4
5

> **注意**：执行前请先备份。
>
> ```bash
> cp -r data data.bak

  引用常用于：摘录别人的话、强调注意事项、写“备注”。

8 表格

  源码：

1
2
3
4
| 名称 | 说明 | 价格 |
|:---|:---|:---:|
| 苹果 | 水果 | 5 元 |
| 螺丝刀 | 工具 | 12 元 |

  渲染效果：

名称 说明 价格
苹果 水果 5 元
螺丝刀 工具 12 元

  第二行那串 --- 是分隔行，必须写，它用来区分表头和内容。

  冒号控制对齐方式。源码：

1
2
3
4
| 左对齐 | 居中 | 右对齐 |
|:---|:---:|---:|
| 内容 | 内容 | 内容 |
| 长一点的内容 | 长一点的内容 | 长一点的内容 |
左对齐 居中 右对齐
内容 内容 内容
长一点的内容 长一点的内容 长一点的内容

  单元格里可以用其他语法：

1
2
3
4
5
| 格式 | 示例 |
|:---|:---|
| 粗体 | **加粗的文字** |
| 代码 | `npm install` |
| 链接 | [百度](https://www.baidu.com) |
格式 示例
粗体 加粗的文字
代码 npm install
链接 百度

  表格里不能用竖线——| 会被当成单元格分隔符。要打竖线得写成 \|：

1
2
3
| 符号 | 写法 |
|:---|:---|
| 竖线 | \| |
符号 写法
竖线 |

  表格的局限：不能有空行、不能跨行合并单元格、不能设置单元格背景色。要复杂表格得直接写 HTML。

9 分隔线

  单独一行写三个或更多的 -、*、_：

1
2
3
4
5
上面的内容

---

下面的内容

  渲染效果：

上面的内容

下面的内容

  注意：--- 在文件开头有特殊含义（表示 front-matter 的分隔符），别在该用的地方误用。

10 转义

  如果你想显示 Markdown 的符号本身，而不是让它生效，就在前面加反斜杠。源码：

1
2
3
\*这不是斜体\*
\# 这不是标题
\_这不是斜体\_

  渲染效果：

*这不是斜体*
# 这不是标题
_这不是斜体_

  常见需要转义的字符：

字符 转义写法
\ \\
` \`
* \*
_ \_
{ } \{ \}
[ ] \[ \]
( ) \( \)
# \#
+ \+
- \-
. \.
! \!
| |

11 段落与换行

  这是最容易出错的一块，单独讲。

11.1 段落：空一行

  源码：

1
2
3
4
这是第一段。
这行还属于第一段。

这是第二段。

  渲染效果：

这是第一段。
这行还属于第一段。

这是第二段。

  不空行的话，两行会被合并成一段。 这是新手最常遇到的困惑——明明在源码里换行了，渲染出来却连在一起。

11.2 强制换行：行尾两个空格

  如果确实想让同一段内的两行断开，在行尾加两个空格：

1
2
第一行（行尾有两个空格）  
第二行

  渲染效果：

第一行（行尾有两个空格）
第二行

  但这两个空格看不见，很容易被编辑器自动删掉（很多编辑器有“保存时删除行尾空格”的功能）。所以更稳的做法是空一行另起一段。

  也可以用 HTML 的 <br>：

1
第一行<br>第二行

第一行
第二行

11.3 缩进

  Markdown 默认不支持段落首行缩进。想缩进有两种办法：

  ——用全角空格 　（U+3000）；
  ——用 HTML 实体 &emsp;。

  这个博客用的是 &emsp;&emsp;（两个全角空格）来实现中文段落的缩进效果。

12 内联 HTML

  Markdown 允许直接写 HTML，这补上了它缺失的一些能力。源码：

1
2
3
4
5
这段文字<sup>上标</sup>和<sub>下标</sub>。

<center>这行会居中</center>

<kbd>Ctrl</kbd> + <kbd>C</kbd>

  渲染效果：

这段文字上标和下标。

这行会居中

Ctrl + C

  常见用途：

需求 HTML 写法
上标 <sup>文字</sup>
下标 <sub>文字</sub>
居中 <center>文字</center>
键盘按键 <kbd>Ctrl</kbd>
强制换行 <br>
折叠 <details><summary>标题</summary>内容</details>

  但有个坑要注意：HTML 块内部的内容不按 Markdown 解析。比如：

1
<center>这里的 **加粗** 不会生效</center>

  渲染出来就是 <center>这里的 **加粗** 不会生效</center> ——星号原样显示。要加粗得直接写 <b>：

1
<center>这里的 <b>加粗</b> 会生效</center>
这里的 加粗 会生效

  这个特性还会影响别的：某些渲染器里，写在 HTML 标签内的数学公式 $...$ 也不会被处理。遇到公式不渲染时，先看看是不是被 HTML 标签包住了。

13 脚注

  源码：

1
2
3
这里有个说法需要注脚[^1]。

[^1]: 这是注脚的内容。

  渲染效果：

这里有个说法需要注脚[1]。

  脚注的支持度不如其他语法，有些平台不支持。写博客时用得不多，写学术类文档时比较有用。

14 几个实用建议

  ① 段落之间空一行。 前面说过，这是最常踩的坑。

  ② 中英文之间加空格。 习惯问题，但读起来舒服很多。比如写“使用 Python 脚本”而不是“使用Python脚本”。

  ③ 标点用中文全角。 中文内容里用 ，。：； 而不是 ,.:;。引号也要用全角的 “”，不要用英文的 ""——同一篇文章里混着用会很明显。

  ④ 文件名和路径用英文。 中文路径在有些工具链上会出编码问题。

  ⑤ 一个文件一个主题。 别把所有笔记堆在一个巨大的 md 里，以后找不到。

  ⑥ 标题层级不要跳。 从 ## 直接跳到 ####，目录结构会有问题。

  ⑦ 表格别太宽。 手机上看超过 4～5 列的表格会很难受。列多的信息考虑改成列表或分几张表。

15 用什么写

工具 特点 价格
VS Code 免费，装 Markdown 插件就有实时预览。写代码的人顺手就用它 免费
Typora 所见即所得，写完直接是排版后的样子 收费
Obsidian 笔记软件，支持双向链接，适合建知识库 免费
Logseq 大纲式笔记，也支持双链 免费
语雀 / Notion 在线，能协作，导出 Markdown 也方便 有免费版
纯文本编辑器 记事本也行，就是没预览 免费

  我个人日常用 VS Code 写技术文章，用 Obsidian 记零散笔记。工具不重要，选一个用顺手的一直用下去就行。

16 最后

  Markdown 的整个语法，一页纸就能印完。它不是一门需要“学”的语言，而是一种写字的习惯。

  真正要注意的不是语法，而是内容组织：标题层级合不合理、列表有没有嵌套太深、表格有没有必要、一段话是不是太长。这些跟用什么标记语言没关系。

  语法忘了随时查，网上速查表一大把。先用起来。

  1. 这是注脚的内容。 ↩︎

许可协议

本文由Primerusse原创，采用CC BY-NC-SA 4.0 许可协议，转载请注明出处。

分享文章