常见坑

每一章对着一个报错或一个现象：先用最小的程序复现，再到源码里找它从哪一行来，最后给出修法和检查办法。前面几部分讲过的机制，这里只链过去。

复现环境都是 M2 Max、macOS 27、rustc 1.99.0、pulldown-cmark 0.13.5；和 0.13.4 不同的地方，章里写明。有几个坑是上游的问题，章里写明 tag 之后的 main 上改了没有。

选项与 feature

1. Parser::new 不认表格和脚注：Parser::new 等于 Options::empty()，脚注定义还会被当成链接定义。
2. ENABLE_GFM 只开了提示块：表格、删除线、任务框、脚注各有自己的位，裸网址不会变成链接。
3. 开了 simd，ARM 上什么都没变：SIMD 只在 x86_64 编译；README 的命令还会把 html 去掉。
4. E0433: cannot find html in pulldown_cmark：--no-default-features 连 html 模块一起去掉；工作区里别的成员会把这个错误遮住。

渲染与安全

5. push_html 原样输出 <script>：原始 HTML、javascript: 链接和图片、标题属性里的事件处理器都能过去，没有开关。
6. 只过滤掉 End 事件，HTML 悄悄坏掉：push_html 不检查配对，删一端就留下没闭合的标签或吞掉后文。
7. 标题没有 id，{#id} 原样显示：自动锚点要自己做；开了标题属性，结尾的花括号都会被当成属性。

文本与偏移

8. 一段文字被切成好几个 Text：实体、转义、方括号都会切开文字，按事件搜索替换会漏。
9. &doc[range] 切不回原文，还会 panic：范围是节点的源文区间，不是事件文本的位置。
10. E0271: OffsetIter yields (Event, Range)：带偏移的迭代器不能直接交给 push_html。
11. 链接定义写在后面，分段渲染就断了：要整份文档跑完第一遍才有第一个事件。
12. 引用链接静默变成了文字：展开预算用完后，后面的引用链接留作文字，回调也不调。

中文内容

13. **结论。**正文 原样显示星号：闭合 ** 前是全角标点、后面紧跟汉字时配不上。
14. 原价$5，现价$3 变成了公式：开了数学，两个不带空格的 $ 之间就是行内公式。

脚注、表格与其他块

15. 脚注的第二段成了代码块：GitHub 风格和旧风格对同一段输入给出不同结构。
16. 脚注 [^Note] 编号对不上、链接跳不过去：解析不分大小写，push_html 的编号分。
17. 表格里代码段的 | 把单元格切开了：切单元格在行内解析之前，反引号挡不住。
18. 文档中间被分隔线包住的一段不见了：元数据块不只认文件开头。
19. </SCRIPT> 没有结束 HTML 块：只认小写且同名的结束标签，后文全进了 HTML 块。
20. 结束围栏后多了一个制表符，代码块吞掉了后文：结束围栏后只允许空格。

版本

21. 旧版本上几百 KB 的输入要解析好几秒：0.13.5 摘进了三个超线性修复，处理不可信输入就升级并限制长度。