Markdown 速查：一份务实的快速教程

大多数文档最初都只是一个带几个星号和井号的纯文本文件。这个文件通常就是 Markdown。它不是为 Web 写作的唯一方式，却是 README、问题追踪器、聊天机器人和静态站点的默认格式，因为它在渲染之前就能被直接阅读。

这是一份务实的快速教程。假设你只有十分钟和一个文本编辑器，不需要安装任何东西。

Markdown 是什么

Markdown 是一种轻量级标记语法。John Gruber 在 2004 年发布原始规范时只有一个目标：让纯文本看起来舒服，并且能干净地转成 HTML。如今它已成为 GitHub、Obsidian、Notion、多数静态网站生成器，以及大多数大语言模型输出的输入格式。

核心思想很简单：用标点符号而不是标签来标记结构。

# 这是一个标题

这是一个段落。

- 这是列表项
- 这是另一项

解析器会把这段内容转成 HTML。不同解析器支持不同扩展，这正是标准变得重要的原因。

Markdown 标准很重要

Markdown 没有唯一的官方标准。Gruber 的原始规范留有空隙，不同工具用互不兼容的方式填补了它们。如果你在一个应用里写了一张表格，再粘贴到另一个应用，它可能会坏掉。所以要知道自己面向的是哪种方言。

• CommonMark。 2014 年启动的严格、经过充分测试的规范，精确定义了核心语法。如果你想要可移植性，就写 CommonMark。
• GitHub Flavored Markdown（GFM）。 增加了表格、任务列表、删除线、围栏代码块和自动链接。GitHub README 和 issue 评论用的就是它。
• Pandoc Markdown。 增加了引用、脚注、定义列表、上下标和数学公式。学术界很常见。
• Obsidian / Quarto / MDX。 增加了维基链接、标注、可执行代码单元或嵌入组件。功能强大，但可移植性差。

日常工作选 GFM 最安全。如果文档可能会在多个工具之间迁移，CommonMark 加一组有文档记录的扩展是更好的选择。

Markdown 基础

标题

使用一到六个井号。一个井号最大。

# 一级标题

## 二级标题

### 三级标题

段落与换行

段落之间用空行分隔。行尾加两个空格或反斜杠可以强制换行。

这是第一个段落。

这是第二个段落。

强调

_斜体_ 或 _斜体_
**粗体** 或 **粗体**
**_粗体加斜体_**
~~删除线~~（仅 GFM）

列表

无序列表用 -、* 或 +：

- 第一项
- 第二项
  - 嵌套项

有序列表用数字：

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

数字不一定要正确，渲染时 Markdown 会重新编号。不过为了让源码可读，还是建议按顺序写。

链接与图片

[链接文字](https://example.com)
[带标题的链接](https://example.com "标题")
![替代文字](https://example.com/image.png)

内部链接用相对路径：

[Markdown 转 PDF](/tools/markdown-to-pdf)

代码

行内代码用单个反引号：`console.log("hi")`。

代码块用三个反引号：

```python
def hello():
    return "hello"
```

在开头三个反引号后面加上语言标识符，方便语法高亮。

## 常用技巧与示例

### 引用

```markdown
> 这是一段引用。
> 它可以跨越多行。

也可以嵌套：

> 外层引用
>
> > 嵌套引用

分隔线

---

单独一行使用三个或更多短横线、星号或下划线即可。

任务列表

GFM 支持复选框：

- [x] 写完初稿
- [ ] 检查表格
- [ ] 发布文章

它们在 HTML 里渲染为禁用状态的复选框，不能替代真正的表单输入。

转义字符

想让 Markdown 符号原样显示，就在前面加反斜杠：

\*不是斜体\*
\# 不是标题

高级技巧与示例

表格

表格是 GFM 扩展，不属于原始 Markdown 规范。

| 特性     | CommonMark | GFM |
| -------- | ---------- | --- |
| 表格     | 否         | 是  |
| 任务列表 | 否         | 是  |

对齐方式是可选的：

| 左对齐 | 居中 | 右对齐 |
| :----- | :--: | -----: |
| A      |  B   |      C |

尽量保持表格简单。嵌套表格、跨行、跨列都不是标准特性，经常会失效。

脚注

Pandoc 和部分 GFM 解析器支持脚注：

这是一个陈述。[^1]

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

如果需要在渲染后的 PDF 里显示脚注，使用支持 Pandoc 风格语法的转换器，或者手动嵌入。

数学公式

Pandoc 和许多现代编辑器支持 LaTeX 数学：

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

块级公式：

$$
\int_a^b f(x) \, dx = F(b) - F(a)
$$

数学渲染取决于解析器和输出格式。HTML 通常需要 MathJax 或 KaTeX，PDF 转换器通常需要 LaTeX 后端。

定义列表

这是 Pandoc 的另一项扩展：

术语
: 术语的定义。

另一个术语
: 另一个定义。

在 Markdown 中嵌入 HTML

当 Markdown 不够用时，可以直接写 HTML：

<p style="color: red;">这是红色文字。</p>

这适合布局、嵌入视频或 Markdown 不支持的属性。但它会牺牲可移植性，所以要少用。

什么时候需要转换 Markdown

Markdown 适合写作和版本控制，但不适合需要在任何地方看起来都一模一样的最终文档。因此转换器应运而生。

如果你有一份 Markdown 草稿，想把它变成可分享的 PDF，可以使用 Markdown 转 PDF 转换器。它在浏览器中运行，文件不会离开你的电脑。

如果你手里是 PDF，需要可编辑的 Markdown，可以使用 PDF 转 Markdown 转换器。它能提取标题、列表和段落，无需上传到服务器。

Markdown 速记表格

把这张表打印出来贴在显示器旁边，你基本不用再查 Markdown 语法。

结语

Markdown 的优点在于克制。90% 的内容用核心语法就够了，表格、脚注和 HTML 只在文档真正需要时才拿出来。如果你坚持 CommonMark 或 GFM，文件就能在编辑器、平台和转换器之间自由迁移，不会出意外。