Markdown 语法速查,从标题到表格的完整写法

我自己写 README 写了七八年,到现在还是会偶尔卡在某条语法上。不是不会,是写得不够多,某个细节就忘了到底感叹号后面能不能加空格。所以我把常用的几类规则按"写法 + 渲染结果"整理成这篇,你照着抄就行,不用每次都去翻规范。

基础块:标题、强调、列表

标题用井号,一个井号是一级,六个井号是六级,井号和文字之间留一个空格。强调里,单星号或单下划线是斜体,双星号是粗体,三星号粗斜体一起来。

列表分两种。无序列表行首用 -、* 或 + 都行,有序列表用数字加点。嵌套靠缩进,子项缩进两到四个空格。

# 一级标题
## 二级标题

**粗体** 和 *斜体*,还有 ~~删除线~~。

- 苹果
- 香蕉
  - 香蕉是子项
1. 第一步
2. 第二步

渲染出来,标题层级分明,粗斜体生效,香蕉下面缩进出一个子项,有序列表自动编号。这里有个真实的坑:列表或表格上方必须空一行,不然上一段文字会和它合并成一整段。

链接和图片:差一个空格就坏

链接的写法是 [文本](url),想加悬停标题就 [文本](url "标题")。图片几乎一样,前面多一个感叹号:![alt](url)。

关键是感叹号后面不能有空格。! [alt](url) 会被解析成一个前面带字面感叹号的链接,alt 文字也跟着坏掉。这是我见过最多的图片渲染失败原因,没有之一。

给图片套个链接做成可点击徽章,写法是嵌套的:[![alt](图片地址)](跳转地址)。README 顶部那排 shields.io 徽章就是这么并排放的。

[正常链接](https://example.com)
![一张图](https://example.com/img.png)
[![徽章](badge.svg)](https://example.com)

长文档里同一个 URL 引用很多次,可以改用引用式链接 [文本][id],文末再用 [id]: url 单独定义,正文就清爽了。

代码块、引用和表格

行内代码用一对反引号包住,适合句子中间提一个函数名。整段代码用三个反引号围栏,围栏后面可以跟语言名做高亮提示,比如 \\\`python。

块引用行首加 >,可以多层嵌套。分割线是单独一行的三个或更多 - 或 *。

表格是最容易出错的一块。表头一行用 | 分列,紧接一行 --- 做分隔,然后才是数据行。对齐靠分隔行里的冒号::--- 左对齐,:---: 居中,---: 右对齐。

| 名称 | 价格 | 库存 |
| :--- | ---: | :---: |
| 苹果 | 3.5  | 有   |
| 香蕉 | 2.0  | 无   |

这段会渲染成一个三列表格,名称左对齐,价格右对齐,库存居中。单元格里能放加粗、链接、行内代码这类行内格式,但放不了列表或围栏代码块,那是管道表格本身的限制。列数一多手写很折磨,我一般直接用 Markdown 表格生成器 填好再复制走。

GFM 扩展:任务列表和删除线

CommonMark 是严格的标准规范,只管标题、列表、段落、代码、链接、图片、块引用、分割线这些核心。GitHub Flavored Markdown(GFM)在它之上加了几样很常用的东西:表格、任务列表、删除线、自动链接。

任务列表写法是 - [ ] 未完成、- [x] 已完成,GitHub 的 issue 和 PR 里会渲染成可勾选的复选框。删除线用一对双波浪号 ~~文字~~。自动链接是把裸 URL 用尖括号包起来 <https://example.com>,不写文本也能点。

- [x] 写完语法部分
- [ ] 补一个表格例子
- [ ] 跑一遍预览

平台差异:换家就可能点不动

同一份文档在不同平台渲染不完全一样,迁移时最容易翻车的是锚点链接。GitLab 是 GFM 的超集,GFM 锚点照样保留,还额外支持视频音频嵌入和 $...$ 数学公式。但 Bitbucket 给标题锚点加了 markdown-header- 前缀,所以 GitHub 里好好的 [跳转](#某节) 链接搬到 Bitbucket 就点不动了。

还有转义。Markdown 会把某些字符当语法,想打字面值就在前面加反斜杠。价格文案里 *条款适用 会让整行变斜体,改成 \*条款适用 才能原样显示星号;文件名 my_file_name 里的下划线也常被当成强调,写 my\_file\_name 就稳了。

写好之后想确认渲染没问题,可以直接打开 Markdown 语法速查表,每条规则左边是源码右边是实时预览,边对边贴上去试,比脑补靠谱得多。把这几类写法记牢,日常写文档基本不会再卡壳。

---

Made by Toolora · Updated 2026-06-13