Markdown语法详细解析

从一段历史说起

Markdown 是 2004 年由一个叫 John Gruber 的美国程序员发明的。他当时只是觉得，写文档的时候用 HTML 太烦了，满屏的 <p>、<h1>、<strong>，完全偏离了写作的本质。所以他干脆设计了一套简单的语法，让你只关注内容本身，格式交给工具去渲染。这个理念非常聪明，以至于后来 Markdown 火了，从程序员社区一路蔓延到普通用户，现在 GitHub、Notion、语雀、飞书都在用它。

标题：从大到小的层级感

标题是最直观的元素，用 # 符号来表示，一个 # 最大，六个 # 最小。

# 这是最大的一级标题
## 这是二级标题
### 这是三级标题
#### 这是四级标题
##### 这是五级标题
###### 这是六级标题

实际渲染出来就是层层递减的大小关系，一级标题最大最醒目，六级标题最小最紧凑。很多人写文档只用一到三级，这完全够用，因为层级太多反而会让结构显得混乱。

小技巧：在大多数编辑器里，输入 # 加空格后会自动触发标题，非常方便。

段落：最朴素的也是最重要的

段落就是纯文本，两行之间空一行就是新段落。

这是第一段。

这是第二段。

这是第三段。

看起来很 trivial，但其实很多新手都会在这里踩坑——不空行，两段就挤在一起了。Markdown 里，换行不等于分段，这是它和纯文本最重要的区别之一。如果你想在同一个段落里强制换行，可以在行尾加两个空格，或者用一个反斜杠 \。

强调：让重点自己说话

文档里总有你需要加粗、斜体或删除的内容，Markdown 给了你最直接的方式：

这是 **粗体文本**。
这是 *斜体文本*。
这是 ***粗斜体文本***。
这是 ~~删除线文本~~。

效果就是：

粗体：**粗体** 或 __粗体__（两种写法完全等价，看个人习惯）
斜体：*斜体* 或 _斜体_（同样两种写法通用）
粗斜体：***粗斜体*** 或 ___粗斜体___
~~删除线~~：~~删除线~~

这里有个容易混淆的点：在 Markdown 里，_ 和 * 在大多数情况下功能是一样的，可以互换。但如果你在意兼容性，推荐在正式文档中统一用 *，因为 _ 在某些平台上会和斜体混淆。

列表：让条理自己走出来

无序列表

用 -、* 或 + 都可以，效果完全一样：

- 第一项
- 第二项
  - 子项 A
  - 子项 B
* 用星号也可以
+ 用加号照样行

渲染结果就是带有小圆点的列表，子项缩进两层空格即可。

有序列表

用数字加点，数字本身可以连续也可以不连续，渲染时会自动按顺序排：

1. 首先做这一步
2. 然后做这一步
   1. 子步骤一
   2. 子步骤二
3. 最后收尾

注意：有序列表里的数字即使写成 1.、1.、1.，渲染后也会自动变成 1、2、3。但养成从 1 开始递增的好习惯，读源码的时候更清晰。

引用：让文字有自己的”引用感”

引用用 > 开头，支持嵌套：

> 这是一级引用
> > 这是二级引用
> > > 这是三级引用
> 
> 引用里也可以写 **粗体** 和 *斜体*，甚至可以分段。

渲染出来就是一层层向右缩进的文本，视觉上很像邮件里的引用格式。引用块还可以包含其他 Markdown 元素——列表、代码、甚至嵌套引用，非常灵活。

代码：程序员的福音

行内代码

用单个反引号包裹：

用 `pip install` 来安装 Python 包。

渲染后就是类似 pip install 的等宽字体效果，适合在段落里引用命令或变量名。

代码块

用三个反引号包裹，可以指定语言（部分平台支持语法高亮）：

```python
def hello():
    print("Hello, World!")
```

```javascript
console.log("Hello, World!");
```

```html
<!DOCTYPE html>
<html>
<body>
    <h1>Hello</h1>
</body>
</html>
```

这里有个容易出错的地方：反引号必须独占一行，代码块本身不能嵌套反引号。如果你在代码里真的需要写反引号，可以用四个反引号来包裹：

````
这是一个包含 `反引号` 的代码块。
````

常见的代码语言标记

```bash    # Bash 脚本
```python # Python
```javascript 或 ```js  # JavaScript
```css     # CSS
```json    # JSON 数据
```sql     # SQL 查询
```markdown # Markdown 本身

链接与图片：让文档”活”起来

超链接

格式是 [显示文本](链接地址 "可选的标题")：

[访问 GitHub](https://github.com "GitHub 主页")

渲染后点击就能跳转。鼠标悬停在链接上时，会显示 GitHub 主页 这个提示文字。

图片

格式是 ![替代文本](图片地址 "可选标题")：

![一张可爱的猫](https://example.com/cat.jpg "猫咪照片")

![ 和 [ 的区别就在于那个感叹号——加感叹号是图片，不加是链接。这是 Markdown 里最容易记混的两个符号之一。

锚点链接

在同一片文档里，你可以用锚点跳转到特定位置：

[回到顶部](#顶部)
[跳到表格部分](#表格)

对应的目标位置需要用标题语法来定义，比如 # 顶部 就可以作为一个锚点目标。

表格：比 HTML 优雅多了

表格是 Markdown 里稍微复杂一点的元素，但只要记住格式就很简单：

| 左对齐 | 居中对齐 | 右对齐 |
| :----- | :------: | -----: |
| 内容1  |  内容2   |  内容3 |
| 内容4  |  内容5   |  内容6 |

渲染后：

左对齐	居中对齐	右对齐
内容1	内容2	内容3
内容4	内容5	内容6

|:---| 表示左对齐，|:---:| 表示居中，|---:| 表示右对齐。第一行是表头，第二行是分隔线，下面每行是一个数据行。分隔线里的冒号决定对齐方式，没有冒号默认左对齐。

分隔线：优雅的分割

用三个或以上的 -、* 或 _，单独一行：

---

会渲染成一条横线。这在文档里用来分割不同章节非常有用。

特殊符号与转义

Markdown 里有几个符号有特殊含义：#、*、_、~、`、[、]、(、)、>、|、-。当你真的想输出这些符号本身，而不是让 Markdown 把它们当语法解析时，就用到转义——在符号前面加反斜杠 \：

\# 这不是标题
\$ 这不是变量
\* 这不是斜体
\~\~ 这不是删除线

HTML 标签：Markdown 的隐藏技能

Markdown 本身语法有限，但好消息是——它允许你直接写 HTML。这意味着你可以用 HTML 来做 Markdown 做不到的事情：

<details>
<summary>点击展开看答案</summary>
这是隐藏的内容，只有点击才会显示。
</details>

渲染后是一个可折叠的交互组件，在文档里非常实用。

进阶语法：部分平台支持

任务列表

- [ ] 待完成的任务
- [x] 已完成的任务
- [ ] 另一个待办

渲染后是带有复选框的列表，在 Notion、GitHub、语雀等平台都支持。这个语法在很多笔记软件里被广泛使用。

脚注

这是一段带有脚注的文本[^1]。

[^1]: 这是脚注的内容，会显示在页面底部。

脚注适合在文档里插入补充说明，而不打断正文的流畅性。

数学公式（LaTeX）

行内公式：$E = mc^2$

独立公式：
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

这依赖于平台是否支持 KaTeX 或 MathJax。GitHub 目前不支持行内公式，但 Obsidian、Notion、语雀等工具支持得不错。

快捷键速查

如果你在支持 Markdown 的编辑器里工作，这些快捷键会大幅提升效率：

快捷键	功能
`Ctrl+B`	粗体
`Ctrl+I`	斜体
`Ctrl+K`	插入链接
`Ctrl+Shift+K`	插入图片
`Ctrl+Shift+C`	插入代码块
`Ctrl+Z`	撤销

那些新手常踩的坑

1. 空格很重要

有序列表后面必须有空格：1. 这是正确的，而不是 1.这是错误的。代码块里的缩进也要严格，Python 的缩进错误在 Markdown 里同样会被保留。

2. 图片链接的替代文本

![ 后面的文字是”替代文本”，不是图片说明。当图片加载失败时，用户会看到这段文字。写替代文本的时候尽量描述图片内容，比如 ![一张可爱的橘猫] 而不是 ![图片]。

3. 平台差异

GitHub Flavored Markdown（GFM）是业界最通用的标准，但不同平台支持的扩展语法不同。比如任务列表、脚注、表格对齐，在 GitHub 上支持得不错，但在某些纯文本编辑器里可能无效。写文档前最好先预览。

4. 长文档的结构

超过 1000 行的 Markdown 文件，建议用目录来组织内容。虽然 Markdown 没有内置的目录语法，但你可以手动写一个带链接的目录，然后配合锚点实现跳转。

一个完整的使用示例

假设你要写一份项目文档：

# 项目文档：TaskMaster

> 一个轻量级的任务管理工具

## 简介

TaskMaster 是一个用 Python 编写的命令行任务管理工具，支持任务创建、完成、删除和分类。

## 安装

```bash
pip install taskmaster

快速开始

import taskmaster as tm

# 创建任务
task = tm.Task(title="完成周报", priority="高")
task.add()

# 查看所有任务
for t in tm.List().all():
    print(t.title)

配置

在 ~/.taskmaster/config.yaml 中添加：

default_priority: medium
auto_archive_days: 30

已知问题

[ ] 多语言支持尚未完成
[x] Windows 路径兼容性问题已修复
[ ] 批量删除功能待开发

参考

文档最后更新于 2024年1月 “`

这份文档用到了标题、引用、代码块（带语言标记）、列表、复选框、链接，以及分隔线，涵盖了 Markdown 最常见的用法。

总结一下

Markdown 的核心哲学就是用纯文本表达格式，规则简单到近乎直觉：# 是标题，* 是强调，- 是列表，> 是引用，` 是代码。学会这些基础语法，你基本上已经掌握了 90% 的使用场景。剩下 10% 是高级扩展语法，等你在实际工作中碰到需求再去查就好。

写 Markdown 最好的方式就是现在就写——打开一个编辑器，复制上面的例子，改几个字，发出去，看看效果，再改。实践才是最快的学习方式。