跳到主内容
d.devtul.fun
EN
Markdown · 2026-09-26

开发者必备的 Markdown 语法速查表

2026-09-26约 2029 字

只要写代码，你就逃不开 Markdown —— README、Pull Request 描述、Issue 模板、文档，全是它。其中大部分是 GitHub Flavored Markdown（GFM），也就是 CommonMark 的超集，外加少量扩展。这份速查表把源码和它的渲染结果并排摆出来，让你一眼就能核对语法。

标题

用一个到六个 # 表示层级。标题前留一个空行能让解析更稳。

# H1
## H2
### H3

本站页面标题由模板提供 H1，所以正文内容从 H2 起头。

强调：* 与 _ 的区别

两种符号都能做出粗体和斜体，但下划线形式对词边界敏感，只有在词边缘时才会生效。

*italic*     _italic_
**bold**     __bold__
***both***

上面的源码渲染出来是：italic、bold、both。星号能在词中间生效（un*real*istic → unrealistic），下划线不行（un_real_istic 原样保留）。两者可以嵌套，但内外标记最好用不同的符号，否则解析器会犯迷糊。

列表

无序列表用 -、* 或 +；有序列表用数字加小数点。嵌套完全靠缩进 —— 而这正是大家翻车的地方。

1. first
2. second
   - nested a
   - nested b
3. third

- item
- item
  - deeper

缩进错了是经典陷阱：子项必须比父项缩进更多，而且 Tab 和空格混用会把整列顶歪。如果你的嵌套项渲染成了代码块而不是子列表，那就是缩进少了一级。

任务列表

- [ ] todo
- [x] done

渲染成勾选框：- [x] 是已勾选，- [ ] 是未勾选。在 GitHub 的 Issue 里它们是可交互的。

链接

[inline](https://example.com)
<https://example.com>
[ref][1]

[1]: https://example.com "title"

行内链接把文字放方括号、URL 放圆括号；裸 URL 用 < > 包起来就变成自动链接。引用式链接在文末定义一次 URL，正文保持清爽。注意上面自动链接的尖括号做了转义，这样它们会作为源码显示，而不是被解析掉。

图片

![alt text](image.png "tooltip")

语法和链接一样，只是前面多了一个感叹号。第一串是替代文本，引号里的部分是可选标题。

代码

行内代码用单个反引号；围栏代码块用三个反引号，并可附带语言标注来高亮。

`inline code`

```python
def f(x):
    return x * 2
```

绝不要把本想当字面文本展示的 HTML 直接写进正文 —— 在代码围栏里它会原样展示，这也是为什么这份速查表把自己尖括号都做了转义。

表格

表头行之后跟一个分隔行，分隔行里的冒号决定对齐方式。

| Left | Right | Center |
|:-----|------:|:------:|
| a    | b     | c      |

冒号在左就左对齐，在右就右对齐，两边都有就居中。表格单元格里不能放代码围栏或嵌套表格这类块级元素 —— 在单元格里放围栏代码块会把整张表搞坏。

引用块与分隔线

> 一段引用
> 跨两行

---

> 前缀构成引用块；单独成行的三个以上短横、星号或下划线构成水平分隔线。这里的 > 做了转义，这样例子展示的是源码，而不是真的变成引用。

转义

想展示一个本来会被 Markdown 解释掉的字符，就在它前面加反斜杠：\*不是斜体\* 渲染为 \*不是斜体\*。靠它你能放心地写 "C++" 而不必担心被误解，也能在行首展示一个字面的井号。

脚注

这里 GFM 和 CommonMark 分道扬镳。在 GitHub 上你这样写：

带脚注的文字。[^1]

[^1]: 脚注内容。

严格的 CommonMark 根本没有脚注语法，所以在完全遵循规范的渲染器上，同样的文字只会把方括号原样显示出来。如果要在多处通用，宁可把注释放进正文。

混写原生 HTML

因为 Markdown 是 HTML 的超集，你可以直接塞入原生 HTML 块。这对 Markdown 缺少的东西很有用，比如换行或定义列表。但要记住页面可能会清洗标签，所以别假设每个元素都能存活。

GitHub 特有的扩展

  • @提及 如 @octocat 会通知某个用户或团队。
  • Issue 引用 如 #123 会链接到同仓库的 Issue 或 PR。
  • 任务列表 - [x] 在 Issue 和 PR 里渲染成勾选框。
  • 删除线 ~~done~~ 渲染为 done。
  • 自动链接引用 如 SHA、username/repo#1、#123 会被自动加链接。

那些"看起来能用其实不行"的写法

  • 表格单元格里放代码围栏。表格只能容纳行内内容；围栏会把整行弄成一团乱码。
  • 看着对齐其实没对齐的缩进。行首四个空格是代码块，不是子列表 —— 如果你的嵌套列表变成了等宽文本，原因就在这。
  • 词中间的下划线。file_name 会原样保留，而 file-name 没问题；只有星号能给词中间加强调。
  • 一个单元格里放多个段落。GFM 不支持，换行就结束了这个单元格。

下次 README 渲染出错时，把这份表放在手边：十次里有九次是缩进或转义的小疏忽，而不是 Markdown 的 bug。

继续阅读