上周五晚上十一点,朋友发过来一条消息,就一句话:“救救我,我排了一晚上的文档,发出去全散了。”
点开她发来的截图,是一篇项目复盘:明明写了“第一、第二、第三”三步操作,发布到平台上之后,第一步变成了普通段落,第二步缩进到了代码块里,第三步干脆消失了。她在 Word 里调好的格式,复制进 Markdown 编辑器的那一刻,就像把一盒乐高倒进了洗衣机——零件都是好零件,出来就是一锅粥。
这是几乎所有刚开始用 Markdown 的人都会踩的坑。列表看起来是 Markdown 里最简单的东西,不就是一个减号一个空格吗?可正是这种“看起来简单”,让多数人从没认真学过它的规则。而 Markdown 的规则又偏偏很反直觉:它不报错,不弹窗,你写错了它就默默地、错误地渲染出来,全靠你自己发现。
这篇文章把列表这件事拆开讲透,全是能上手的干货。
一、先想清楚:你要的是“顺序”,还是“并列”
很多人列表出问题的根源,不在语法,在选错了列表类型。
技术写作圈子里流传一句话:圆点暗示自由,数字暗示结构。步骤、流程、优先级——凡是顺序错了结果就错的东西,必须用有序列表:
1. 点击右上角齿轮图标
2. 选择"设置"
3. 找到"通知"选项
如果这三步你用了无序列表(-),读者会下意识觉得“这三件事先做哪个都行”,对着界面一通乱点,配置错了还怪文档写得差。反过来,如果是“我们会提供以下功能”这种并列项,就别用数字,否则读者会琢磨“为什么功能三是最后才讲的,是优先级低吗”——这个排序十有八九是你随手写的,但它已经传递了错误信息。
无序列表的写法:行首写 -、* 或 +,加空格,三种符号效果完全一样。建议一篇文档里只用一种,并且用 -。因为 * 容易和加粗斜体混淆,+ 用的人少。这不是洁癖——有的解析器会把不同符号开头的项识别成两个不同的列表块,中间自动给你插出一段莫名其妙的间距。
(图源:菜鸟教程 Markdown 基础语法页:runoob.com)
还有个小技巧值得知道:有序列表的编号其实可以全写 1.,渲染器会自动排号。这样你在中间插入一步的时候,不用手动把后面十几行的编号全部改一遍——对用 Git 管文档的人来说,diff 记录也干净得多。
二、缩进是列表的命门,Tab 和空格是两种人生
嵌套列表的规则说起来只有一句话:子项比父项缩进 2 到 4 个空格。
- 水果
- 苹果
- 红富士
- 香蕉
- 蔬菜
真正坑人的是执行层面的三个细节,由一份跨六个渲染器的实测背书:
其一,同一个列表里,空格和 Tab 千万别混用。 Tab 在 CommonMark 规范里被当成“前进到下一个 4 的倍数列”,和你想要的缩进层级经常对不上。有人做过测试,同一份用 Tab 缩进的列表,在六个渲染器里四个显示得不一样;全部改成空格后,问题全部消失。所以如果你用 VS Code 写 Markdown,把编辑器的 Tab 键配置成插入空格。
其二,缩进量要全文统一。 这一层用 2 空格,下一层突然用 4 空格,解析器会懵——它可能把 4 空格那行当成代码块,你的列表里就凭空多出一块等宽字体灰底文字。
其三,列表前面记得空一行。 特别是段落紧挨着列表开头的时候,不少解析器(包括 GitHub)需要这个空行才能正确识别,否则整段列表被当成普通文本。
(图源:itsFOSS Markdown 语法指南:itsfoss.com)
三、任务列表:一个空格引发的“灵异事件”
任务列表是 GitHub 在 2013 年加进 GFM(GitHub Flavored Markdown)的扩展语法,写法是 - [ ] 未完成任务 和 - [x] 已完成任务。现在 Obsidian、VS Code、Typora 都支持,做待办清单几乎是笔记软件的标配。
(图源:GitHub 官方博客:github.blog)
但它是翻车率最高的语法,没有之一。排查复选框不显示的顺序应该是这样:
- 检查空格。
- [ ]里最容易漏的是]后面那个空格,少了它,整行就是普通文字。 - 检查列表标记。直接写
[ ]是不行的,前面必须有-、*或+。 - 检查平台。任务列表是扩展语法,原始 Markdown 规范里没有,一些老旧渲染器会直接显示成
- [ ] 文字的裸文本。 - 检查缩进。嵌套任务列表的子项要和父项文字对齐,Tab 和空格不能混。
还有个更隐蔽的坑:在 GitHub 上,Issues 和 Pull Request 里的任务列表是可以点击勾选的,但 README.md 里的任务列表是只读的。你在仓库首页看到一个完成度 60% 的 checklist,点了没反应,不是 Bug,是设计如此——想改状态,得去编辑源文件,把 [ ] 换成 [x]。如果项目进度靠 README 里的复选框汇报,建议还是写清楚百分比数字,别让读者对着一个点不动的框干着急。
四、列表里塞代码块:对齐到“文字”,不是对齐到“行首”
进阶玩法:列表项里可以放段落、引用、代码块、图片,几乎任何块级内容。规则仍然只有一句——所有延续内容,缩进到和列表项文字对齐的位置:
1. 安装依赖:
```bash
npm install markdown-it
- 在代码中引入:
import markdownit from 'markdown-it'
”`
注意那个三空格缩进:它不是随便来的。1. 这个标记符占了 2 个字符加一个空格,文字从第 4 列开始,所以代码块的围栏标记也要从第 4 列开始。很多人顺手缩 4 个空格,差一格,列表当场断裂,代码块跑到列表外面去了。
在 Obsidian 这类编辑器里还有一个高频灵异现象:你在任务列表下想接一段普通说明文字,回车后编辑器自动继承了任务列表格式,怎么删都删不掉。正确做法是回车后先按退格键,清掉自动继承的格式,再开始写。这不是编辑器抽风,是它在严格执行“列表项内延续内容要对齐”这条规则——你只是还没习惯它的思路。
最后提醒一句平台差异:GitHub、GitLab 嵌套列表 2 个空格就够,Bitbucket 和 Reddit 要 4 个,Pandoc 默认按 4 个处理。一份文档要在多个平台流转的话,统一用 4 空格是最稳妥的选择;另外字母列表(a. b. c.)和罗马数字列表在任何主流平台都不支持,别指望了。
写在最后
回到开头那位朋友的深夜求助。我让她把文档发过来,改了十分钟——无非就是段落和列表之间补了空行、Tab 换成空格、步骤改回了有序列表。她说:“就这么点东西,我折腾了三小时。”
这就是 Markdown 列表的真相:它没有黑魔法,只有几条没人提前告诉你的规矩。圆点是并列,数字是顺序,缩进对齐文字列,空格永远别混 Tab。 记住这四句,你以后排文档的时间,至少能省下一半。
你写列表踩过最离谱的坑是什么?评论区聊聊,说不定你的坑就是我下篇文章的素材。
(参考来源:Markdown Guide - Basic Syntax、CommonMark Spec - Lists、jmmv.dev - Markdown Lists、zuizhinan.com - Markdown 列表语法教程、MacMD Viewer - Markdown Lists Guide)
