Markdown 中文加粗失灵实录:CommonMark 标点规则与 4 个渲染器对拍
TL;DR:加粗号的内侧(紧挨被强调文字的那一侧)贴着全角标点、而外侧(另一侧)是汉字或拉丁字母时,CommonMark 判定这一侧「不构成贴合」,整对星号一起失效,页面上留下字面星号,而编辑器预览、构建日志、审稿脚本全都不报错。我实际把 32 组字符组合与 14 条真实句子喂进 markdown-it-py 4.2.0、mistune 3.4.0、GitHub 官方 GFM 接口、Python-Markdown 3.11.3:前三者逐组完全一致,14 条句子里有 10 条渲染成字面星号;Python-Markdown 则 14 条全部渲染成功。这不是谁有 bug,而是两份实现选了不同的规范解释。改法有三种,把标点挪到星号外侧最稳。
现象:预览里是粗体,线上只剩一串星号
这个坑我踩了不止一次。第一次是在写中文技术文时用「注意:」开头的加粗提示行,编辑器分栏预览显示粗体,提交到静态站点后页面上出现的是两个字面星号加一个全角冒号。查 HTML 源码,那一行就是一段普通段落,没有任何异常标记,构建日志里也没有一条警告。
第一反应是怀疑自己的渲染器写错了。于是我把那一行原样粘到 GitHub 的评论框里,同样不是粗体。这条线索很关键:如果 GitHub 也不认,那问题就不在某个具体实现,而在 Markdown 的规范层。
顺着这条线查下去,会发现这不是一个偶发的解析 bug,而是一条写进规范、有明确定义、也早有人报过但至今未改的规则。它影响的不只是加粗,斜体、下划线形态的强调、表格、列表、分隔线都有同一个源头。
规则原文:贴合到底怎么算
CommonMark 0.31.2 的 6.2 节先把「分隔符串」分成左侧贴合与右侧贴合,再规定什么时候能开、什么时候能关。原文如下:
A left-flanking delimiter run is a delimiter run that is
(1) not followed by Unicode whitespace, and either
(2a) not followed by a Unicode punctuation character, or
(2b) followed by a Unicode punctuation character and
preceded by Unicode whitespace or a Unicode punctuation character.
For purposes of this definition, the beginning and the end of
the line count as Unicode whitespace.
A right-flanking delimiter run is a delimiter run that is
(1) not preceded by Unicode whitespace, and either
(2a) not preceded by a Unicode punctuation character, or
(2b) preceded by a Unicode punctuation character and
followed by Unicode whitespace or a Unicode punctuation character.
5. A double asterisk can open strong emphasis
iff it is part of a left-flanking delimiter run.
7. A double asterisk can close strong emphasis
iff it is part of a right-flanking delimiter run.
两段定义里都有一个 2b 分支,意思是:贴着标点也可以,但另一侧必须是空白或标点。这一句就是全部问题的来源。
再补一条同规范 2.1 节的定义,它决定了「标点」这个词的边界:
A Unicode punctuation character is a character in the Unicode P
(puncuation) or S (symbol) general categories.
括号里那个 puncuation 是规范原文的拼写错误,至今没有改。
全角标点为什么必然触发
关键在 Unicode 的类别划分。我用标准库把中文写作里最常见的十几个标点逐一打出来:
| 字符 | Unicode 类别 | 名称 |
|---|---|---|
| 「 | Ps | LEFT CORNER BRACKET |
| 」 | Pe | RIGHT CORNER BRACKET |
| ( | Ps | FULLWIDTH LEFT PARENTHESIS |
| ) | Pe | FULLWIDTH RIGHT PARENTHESIS |
| , | Po | FULLWIDTH COMMA |
| 。 | Po | IDEOGRAPHIC FULL STOP |
| : | Po | FULLWIDTH COLON |
| ! | Po | FULLWIDTH EXCLAMATION MARK |
| ? | Po | FULLWIDTH QUESTION MARK |
| 、 | Po | IDEOGRAPHIC COMMA |
| — | Pd | EM DASH |
| … | Po | HORIZONTAL ELLIPSIS |
| “ | Pi | LEFT DOUBLE QUOTATION MARK |
| ” | Pf | RIGHT DOUBLE QUOTATION MARK |
全部落在 P 大类里,因此全部算 Unicode 标点字符。而汉字属于 Lo(Letter, other),既不是空白也不是标点。
于是结论很清楚:中文加粗本身没有问题。两端都是汉字的加粗在四个渲染器里都正常,因为开标记后面是汉字、闭标记前面是汉字,2a 分支成立。真正出问题的是内容两端为中文标点的情形:此时开标记后面是标点,要走 2b,而 2b 要求开标记前面是空白或标点,中文句子里开标记前面紧挨的往往是汉字,2b 不成立,开标记作废。闭标记同理。
中文排版不用空格分词,标点前后也不加空格,所以这一条对西文几乎无感的规则,在中文里几乎每条都会撞上。
32 组组合与 14 条真实句子
只看定义容易自我说服,所以我做了全因子实测:前字符取汉字、全角冒号、空格、拉丁字母四种,内侧字符取汉字、全角冒号两种,后字符取汉字、全角句号、空格、拉丁字母四种,共 32 组。节选几组最有信息量的:
| 前字符 | 内侧字符 | 后字符 | markdown-it-py | mistune | GitHub GFM | Python-Markdown |
|---|---|---|---|---|---|---|
| 汉字 | 汉字 | 汉字 | 渲染 | 渲染 | 渲染 | 渲染 |
| 汉字 | 全角冒号 | 汉字 | 字面 | 字面 | 字面 | 渲染 |
| 汉字 | 全角冒号 | 全角句号 | 字面 | 字面 | 字面 | 渲染 |
| 全角冒号 | 全角冒号 | 全角句号 | 渲染 | 渲染 | 渲染 | 渲染 |
| 全角冒号 | 全角冒号 | 汉字 | 字面 | 字面 | 字面 | 渲染 |
| 拉丁字母 | 全角冒号 | 拉丁字母 | 字面 | 字面 | 字面 | 渲染 |
| 空格 | 全角冒号 | 汉字 | 字面 | 字面 | 字面 | 渲染 |
32 组的汇总:markdown-it-py 出粗体 20/32,mistune 20/32,GitHub 官方接口 20/32,三者逐组完全相同;Python-Markdown 32/32 全部出粗体。也就是说严格按照规范实现的那三条路径里,有 12 组失效,占全部组合的 37.5%,而这 12 组全部落在「标点紧贴加粗号内侧」这一类。
再叠一层真实句子。下面 14 条里前 10 条是这次实际对拍到的失败样本,后 4 条是能正常工作的对照:
**テスト。**テスト 日本句号收尾
**テスト、**テスト 日本逗号收尾
这是**我想做的事。**所以继续。 中文句号收尾
这是**「重要的」**内容。 中文引号包裹
これは**「重要なこと」**です。 日文引号包裹
문서를 작성할 때 **마크다운(Markdown)**을 사용하세요.
**)**a 半角括号收尾、后接字母
**具体:**与其说「一棵树」 全角冒号收尾
这是**「重要的」** 内容。 只在闭标记后加空格
**)**! 收回标记后接标点
----- 以下 3 条为对照,全部能渲染 -----
这是 **「重要的」** 内容。 两侧都留空格
这是**重要的**内容。 两端都是汉字
**注意:**(该操作不可撤销) 标点挪到星号外侧
前 10 条在 markdown-it-py、mistune、GitHub 三个口径里全部是字面星号;Python-Markdown 14 条全过。第 9 条特别值得记:只在闭标记一侧加空格不够,开标记那一侧仍然失效,整对星号照样作废。
复现脚本:三分钟在自己机器上重跑
下面这段可以直接复制执行,只依赖三个纯 Python 包,不需要 API key:
python -m pip install --target ./mdprobe markdown-it-py mistune markdown
import sys
sys.path.insert(0, "./mdprobe")
from markdown_it import MarkdownIt
import markdown as pymd
import mistune
cm = MarkdownIt("commonmark")
mk = mistune.create_markdown()
CASES = [
"这是**「重要的」**内容。",
"这是**我想做的事。**所以继续。",
"这是 **「重要的」** 内容。",
"这是**重要的**内容。",
]
for src in CASES:
a = "<strong>" in cm.render(src)
b = "<strong>" in pymd.markdown(src)
c = "<strong>" in mk(src)
print("%-28s mit=%-5s pymd=%-5s mist=%-5s" % (src, a, b, c))
期望输出里第一条是 False/True/False,第三条与第四条三个都是 True。只要第三条为真、第一条为假,就说明你的渲染器走了严格 CommonMark 这条路。
想复算 GitHub 自己的结果,官方有一个公开的渲染端点,把 mode 设成 gfm 即可:
curl -s -X POST -H "Content-Type: application/json" -d "{\"text\":\"这是**「重要的」**内容。\",\"mode\":\"gfm\"}" https://api.github.com/markdown
返回的是一段普通段落,星号原样保留。
三种改法,只有一种不需要解释
改法一,把标点挪到星号外侧。加粗内容末尾的冒号、句号、括号一律移到星号后面,或者写成「标点本来就在粗体外面」的形式。零副作用,读者看到的排版语义反而更准:粗体只包住内容,不包住标点。
改法二,在星号外侧加空格。这在四个渲染器上都能救回来,但中文里凭空多两个空格很难看,而且只在单侧加空格不算(前面第 9 条已经实测)。想避免视觉空隙可以用零宽空格 U+200B 放在内侧:它是 Cf(格式字符)类,既不算空白也不算标点,正好让 2a 分支成立。我实测把零宽空格放在引号左右两侧的内侧位置,markdown-it 与 GitHub 都能出粗体。
这里有个反直觉的点:不要用 NBSP(U+00A0)。它属于 Zs 类,是货真价实的 Unicode 空白,放进内侧会让开标记后面变成空白,2a、2b 同时不成立,照样失效。名字里带「不换行空格」,规则里一样当空格算。
改法三,直接用 HTML 的 strong 标签。最稳,跨渲染器一致,缺点是可读性差、混在正文里不自然。适合批量脚本生成的内容,不适合手写。
我自己的选择是按顺序来:先试改法一,改不动(比如整句被引号包住、标点必须留在粗体里)再用零宽空格,批量生成的场景才用 strong 标签。
同源陷阱一:编号不是 1 的列表不会打断段落
贴合规则之外,CommonMark 里还有几处看着应该生效、实际静默失效的语法,源头不同但体感一样。最典型的是有序列表的起始编号。规范在列表项的定义后面跟了一条例外:
1. When the first list item in a list interrupts a paragraph -- that is,
when it starts on a line that would otherwise count as paragraph
continuation text -- then (a) the lines Ls must not begin with a blank
line, and (b) if the list item is ordered, the start number must be 1.
翻译过来:列表想打断一个正在进行的段落,有序列表的起始编号必须是 1。所以下面两行的结局完全不同:
正文第一句。
1. 第一项
正文第一句。
3. 第三项
前者会切成段落加有序列表;后者整块是一个段落,GitHub 上只是把换行渲染成一个折行。这条规则对写「三、四步」的人很致命:你从 3 开始编号,读者的页面上看到的是一段带 3. 的文字,不是列表。
规避办法只有两个:在列表前留一个空行(空行之后就是新块,不再算打断段落,任意起始编号都合法),或者把编号改写成手写序号配合项目符号。
同源陷阱二:分隔线会把上一行变成二级标题
几个减号独占一行本意是分隔线,但如果它上面紧贴着一段文字,规范里写明了优先级:
If a line of dashes that meets the above conditions for being a
thematic break could also be interpreted as the underline of a
setext heading, the interpretation as a setext heading takes precedence.
也就是说一段正文换行接三个减号,得到的是二级标题,而不是「段落 + 分隔线」。四个渲染器在这条上完全一致,包括 Python-Markdown。我在自己的生成器上吃过这个亏:文末想加一条分隔线,结果上一行的总结句变成了全站唯一的二级标题,而当时的 HTML 审查只看 h1 数量。
判断方法很简单:分隔线的前后各留一个空行。
同源陷阱三:表格根本不在 CommonMark 里
这件事很多人没意识到:CommonMark 规范里没有表格语法。我在规范全文里搜 table 这个词,26 处命中全部是 HTML 块里的标签例子,没有一处定义管道表格。
所以管道表格能不能渲染,完全取决于你开没开扩展:
| 渲染器 | 默认是否支持管道表格 | 开启方式 |
|---|---|---|
| markdown-it-py 4.2.0 | 否 | 构造后调用 enable 打开 table |
| mistune 3.4.0 | 否 | 需要 plugins 里的 table 插件 |
| Python-Markdown 3.11.3 | 否 | extensions 传 tables,或直接传 extra |
| GitHub | 是 | GFM 扩展,默认开启 |
这就是为什么同一份 README 在本地跑出来是一段竖线堆叠的段落,粘到 GitHub 就变成表格。它同样不报错。
报错实录:两个真实异常与两条静默失败
上面这些都是静默的。但配置层面确实有几个会抛异常的地方,我在本机(Windows 11、CPython 3.13.14)逐个复现了。
报错一:ModuleNotFoundError: No module named 'tabel'
现象:给 Python-Markdown 传扩展名时少打一个字母,程序直接崩,堆栈里没有任何提示说扩展名拼错了。
>>> import markdown
>>> markdown.markdown("| a | b |", extensions=["tabel"])
ModuleNotFoundError: No module named 'tabel'
原因:Python-Markdown 把扩展名当成模块名去 import,拼错就是导入失败,而异常类型是 ModuleNotFoundError,看起来像缺依赖。我第一次遇到时真去装了一个叫 tabel 的包,当然装不到。
解决:改成 tables(复数),或者直接用 extra 一次带上常用扩展。核对办法是先跑一遍内置扩展清单:
python -c "import markdown; print(sorted(markdown.__all__))"
python -c "import markdown; print([e.name for e in markdown.Markdown().registeredExtensions])"
报错二:yaml.scanner.ScannerError: mapping values are not allowed here
现象:front matter 里写了一行带冒号的描述,解析直接抛 ScannerError,报错位置精确到列,但不解释语义。
>>> import yaml
>>> yaml.safe_load("description: 三层结构: 前端 后端 数据库\n")
yaml.scanner.ScannerError: mapping values are not allowed here
in "<unicode string>", line 1, column 18
原因:YAML 里键与值的分隔符是冒号加空格。值里再出现一组冒号加空格,扫描器就认为这是第二个键值对的开头,而当前位置不允许出现映射。中文写作里用全角冒号不会触发,但只要混进一个半角冒号加空格就必然崩。
解决:把整个值用引号包起来,或者改用全角冒号,或者写成 YAML 的折叠块:
description: "三层结构: 前端 后端 数据库"
静默失败一:linkify 打开了,但什么也没发生
现象:给 markdown-it-py 传 linkify 为真,正文里的裸 URL 依然是纯文本,没有任何异常。
>>> from markdown_it import MarkdownIt
>>> md = MarkdownIt("commonmark", {"linkify": True})
>>> print(md.linkify)
None
>>> print(md.render("见 https://example.com 页面"))
<p>见 https://example.com 页面</p>
原因:linkify 需要另一个包提供识别实现,缺依赖时这个属性就是 None,规则直接跳过。它属于可选依赖缺失的典型形态:不报错、不警告、功能静默关闭。
解决:装齐依赖再打开,或者在初始化后断言一次:
python -m pip install linkify-it-py
python -c "from markdown_it import MarkdownIt; print(MarkdownIt('commonmark', {'linkify': True}).linkify is not None)"
静默失败二:整对星号失效,零日志零告警
现象就是本文开头那个。它不抛异常,因为你写的确实是合法的 Markdown,只是规范把它解释成了普通字符。
原因:贴合规则在 2b 分支上不成立,开标记或闭标记作废,剩下的星号退化成字面文本。
解决:改法见上文三条。另外建议把「产物里出现连续两个星号」做成构建后断言,这一条比任何审稿规则都便宜:
import re, pathlib
PAT = re.compile("<p>([^<]*\*\*[^<]*)</p>")
for p in pathlib.Path("dist").rglob("*.html"):
text = p.read_text(encoding="utf-8")
for m in PAT.finditer(text):
print("字面星号残留:", p, m.group(1)[:60])
写中文 Markdown 的七条检查清单
- 加粗内容的两端若是引号、括号、书名号、冒号、句号、顿号、叹问号、省略号或破折号,先把标点挪到星号外面,比在星号外侧塞空格干净。
- 只在单侧加空格无效,两侧都要满足外部条件,不要只改一半。
- 零宽空格可以救急,NBSP 不行;能选就别用不可见字符,日后排查成本高。
- 有序列表如果从 1 以外的数字开始,前面必须留空行,否则它不会成为列表。
- 分隔线前后各留一个空行,不然上一行会被吸成二级标题。
- 管道表格一律当扩展看,写之前确认目标渲染器开了 table、tables 或 extra。
- 发布前扫一遍产物里的字面星号与竖线段落,这两类残留都是静默的。
结语
这条规则的来龙去脉值得说一句:CommonMark 上游在 2020 年 5 月就有人报了 CJK 标点与强调的冲突(规范仓库的 650 号 issue,至今仍是 open),2026 年 8 月有人提了放宽 CJK 邻接判定的 PR(839 号,目前仍未合并)。markdown-it 那边 2017 年就有一份转报(410 号),2024 年 12 月的 1080 号 issue 专门讲「列表项以中文标点开头时加粗失效」,2026 年 5 月被关掉,但同月提的放宽补丁(1145 号)同样没有进主线。我这次用最新版 markdown-it-py 4.2.0 复测,行为没有变化。
所以别等上游修。把标点挪出去,是成本最低、跨渲染器最稳的一条路。
想继续看同一类的静默失效,也就是那些不报错但结果错的语义坑,可以顺着下面三篇读:Unicode 规范化里七个看起来一样的字符串 讲的是码点层面的看着一样却不相等,Python 正则的八处静默匹配错误 讲的是匹配层面的同类问题,时区与夏令时的六个静默错误 则是时间换算层面的版本。本文为纯技术复盘,不含任何联盟推广链接。
👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务
👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速
📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测
🔗 精选推荐工具
使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):
作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。