← 返回首页

Markdown 中文加粗失灵实录:CommonMark 标点规则与 4 个渲染器对拍

MarkdownCommonMark中文排版

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 类别名称
「PsLEFT CORNER BRACKET
」PeRIGHT CORNER BRACKET
(PsFULLWIDTH LEFT PARENTHESIS
)PeFULLWIDTH RIGHT PARENTHESIS
,PoFULLWIDTH COMMA
。PoIDEOGRAPHIC FULL STOP
:PoFULLWIDTH COLON
!PoFULLWIDTH EXCLAMATION MARK
?PoFULLWIDTH QUESTION MARK
、PoIDEOGRAPHIC COMMA
—PdEM DASH
…PoHORIZONTAL ELLIPSIS
“PiLEFT DOUBLE QUOTATION MARK
”PfRIGHT DOUBLE QUOTATION MARK

全部落在 P 大类里,因此全部算 Unicode 标点字符。而汉字属于 Lo(Letter, other),既不是空白也不是标点。

于是结论很清楚:中文加粗本身没有问题。两端都是汉字的加粗在四个渲染器里都正常,因为开标记后面是汉字、闭标记前面是汉字,2a 分支成立。真正出问题的是内容两端为中文标点的情形:此时开标记后面是标点,要走 2b,而 2b 要求开标记前面是空白或标点,中文句子里开标记前面紧挨的往往是汉字,2b 不成立,开标记作废。闭标记同理。

中文排版不用空格分词,标点前后也不加空格,所以这一条对西文几乎无感的规则,在中文里几乎每条都会撞上。

32 组组合与 14 条真实句子

只看定义容易自我说服,所以我做了全因子实测:前字符取汉字、全角冒号、空格、拉丁字母四种,内侧字符取汉字、全角冒号两种,后字符取汉字、全角句号、空格、拉丁字母四种,共 32 组。节选几组最有信息量的:

前字符内侧字符后字符markdown-it-pymistuneGitHub GFMPython-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 的七条检查清单

结语

这条规则的来龙去脉值得说一句: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 真实评测

🔗 精选推荐工具

使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):

作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。

☁️ DigitalOcean 云服务器 ⚡ Vultr 高性能 VPS 🤖 QoderWork 中国版(推荐有奖) ☁️ 阿里云爆款 AI 产品 📚 WordPress 实用书单 🧠 AI / 大模型书单 🏗️ 系统设计/云架构书单 🐳 Docker/K8s 书单 🐧 Linux 系统管理书单 🐍 Python 编程书单 🗄️ 数据库/PostgreSQL 书单 🚀 DevOps/SRE 书单 🤖 小米 MiMo 开放平台
← 返回首页