# Python Markdown 那些事一个老程序员的自用笔记记得刚接触Python Markdown那会儿正赶上要给项目写文档。团队里有人用Sphinx有人用Jupyter吵得不可开交。最后我默默掏出Python Markdown写了份技术手册三页纸解决了问题。这不是说别的工具不好而是我发现很多时候我们需要的不是一把瑞士军刀而是一把趁手的小刀。一、它到底是什么说白了吧Python Markdown就是一个能把Markdown文本转换成HTML的Python库。听起来简单得不能再简单了对吧但就像炒青菜人人都会可火候、油温、下锅的时机不同味道天差地别。核心就两个东西一个解析器把Markdown语法吃掉吐出一棵语法树然后一个渲染器把这棵树转成HTML。代码层面看大概长这样importmarkdown text# 标题htmlmarkdown.markdown(text)# 输出: h1标题/h1但真正有意思的是它那些扩展机制。比如说标准Markdown不支持表格可Python Markdown通过扩展就能做到。这就好比原本只有三把菜刀现在给你加了个削皮器顺手很多。二、它能帮我们做什么最直接的用途当然是写文档。GitHub的README、Python包的PyPI描述、项目Wiki都靠它。但真正让我觉得这东西牛的地方是它作为一个中间件的能力。举个例子有个老系统每天要生成几千份报告原先用Word模板性能差得要命。后来换了方案数据用Jinja2模板填充成Markdown再用Python Markdown转HTML最后用WeasyPrint转PDF。这一套组合拳下来响应时间从15秒降到0.8秒。另一个场景是博客系统。有时候需要给文章插入代码高亮、数学公式(LaTeX)或者从文章标题自动生成目录。这些活儿Python Markdown都能干而且干得不错。关键是它生成的HTML结构清晰CSS稍微调一下就很美观。还有个小众但非常实用的场景写周报。有人写了个脚本从Jira拉数据生成Markdown格式的周报再用Python Markdown转成邮件可以接受的HTML格式。每周五下午同事们还在手忙脚乱填周报时这个人已经在喝咖啡了。三、怎么在代码里耍它安装很简单pipinstallmarkdown但真正使用起来这里有几个坑要小心。第一默认配置下它连表格都不支持。要激活表格、代码块、目录等特性得这样importmarkdown md_text## 项目进度|模块|完成度|负责人||------|--------|--------||登录|80%|张三||支付|60%|李四|pythondefhello():print(world)“”html markdown.markdown(md_text, extensions[‘tables’, # 表格‘fenced_code’, # 代码块‘codehilite’, # 代码高亮‘toc’, # 目录‘extra’ # 全包扩展])第二代码高亮需要搭配Pygments bash pip install pygments然后代码块就能自动着色了。不过颜色样式需要在HTML里加一句linkrelstylesheethrefhttps://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/default.min.css第三如果你要做些高级操作比如自定义渲染规则可以写自定义扩展frommarkdown.extensionsimportExtensionfrommarkdown.treeprocessorsimportTreeprocessorclassMyExtension(Extension):defextendMarkdown(self,md):md.treeprocessors.register(MyTreeprocessor(md),my_ext,15)classMyTreeprocessor(Treeprocessor):defrun(self,root):# 遍历HTML树做自定义修改forparainroot.iter(p):ifpara.textandpara.text.startswith():# 把以开头的段落变成引用块para.tagblockquotepara.textpara.text[3:]这招儿很管用。有次客户要求所有包含NEXT字样的段落要特别标记我没改Markdown源文件就靠这个扩展在渲染时偷偷替换。四、一些实战经验缓存是王道。别每次请求都重新解析Markdown。特别是大文档解析很费时间。加个lru_cache装饰器或者用Redis存一下渲染结果性能能翻个十倍。安全这块要当心。默认设置下Python Markdown会把用户输入的Markdown里的HTML标签原样输出。这就埋了XSS的雷。如果用户能输入内容记得这样importbleach htmlmarkdown.markdown(user_input)safe_htmlbleach.clean(html,tags[p,h1,h2,em,strong,a],attributes{a:[href,title]})不放心的话还有更深的口子允许的标签列表最好白名单限制死。目录生成有技巧。toc扩展生成的目录默认插在文档开头。但有时候想把它放在侧栏可以这样mdmarkdown.Markdown(extensions[toc])htmlmd.convert(md_text)tocmd.toc# 这玩意儿是HTML字符串然后就可以自己决定把toc放在页面的哪个位置了。比如写个很简陋的双栏布局divstyledisplay:flex;divstylewidth:20%;border-right:1px solid #eee;{{ toc | safe }}/divdivstylewidth:80%;padding-left:20px;{{ content | safe }}/div/div性能调优。纯Python写的东西解析速度当然拼不过C写的库。但如果只是几百行的文档差别几乎感觉不出来。真的遇到超大文档比如系统生成的API文档有上千个接口可以考虑用进程池并行解析。原因很简单Python Markdown解析时受GIL影响多线程帮不上忙但多进程能解决。fromconcurrent.futuresimportProcessPoolExecutordefrender_chunk(chunk):returnmarkdown.markdown(chunk,extensionsEXTENSIONS)withProcessPoolExecutor(max_workers4)asexecutor:resultslist(executor.map(render_chunk,big_doc_chunks))full_html.join(results)调试技巧。有时候生成的HTML不对劲别急着改配置。先把markdown.markdown(text, output_formatdebug)跑一下看看解析器是怎么理解你的Markdown的。这个选项会输出一棵AST一眼就能看出是语法写错了还是解析器理解错了。五、同类技术的比较市面上常见的Markdown解析器有几个md4cC语言实现速度快得吓人。很多编辑器像VS Code后端都用它。但问题是它只做解析不提供灵活的扩展机制而且对Python不友好得用ctypes包一层。mistune也是纯Python写的但设计思路不同。它追求轻量只有几千行代码。扩展支持没有Python Markdown那么深入但在大多数场景下够用。它的强项是速度比Python Markdown快一倍左右。不过文档写得一般Community也不够活跃。marko比较新的项目自称企业级解析器。它支持CommonMark规范解析结果可以序列化成JSON。但说实话这玩意儿现在还有点小众社区插件少。mistune vs Python Markdown就像喝浓缩咖啡和手冲咖啡。Mistune快、轻、干净Python Markdown慢一点但功能丰富。如果你的场景只需要基础的Markdown解析mistune的API更清爽frommistuneimportcreate_markdown markdowncreate_markdown()htmlmarkdown(text)但如果你需要复杂的扩展比如数学公式、自定义块级转换、甚至自己写渲染管道Python Markdown的扩展系统会更顺手。Sphinx严格来说不完全是Markdown解析器它是个文档生成系统。但因为它也支持用Markdown写文档通过MyST扩展所以经常被人拿来对比。Sphinx的优势在于它能生成PDF、ePub、HTML等多种格式而且有完善的交叉引用机制。缺点是太重了配环境就得半小时而且它的Markdown解析不是标准的CommonMark有自己一套规矩。说白了Sphinx适合写书型的长文档Python Markdown适合写文章型的短内容。Pandoc瑞士军刀级别的东西。能读Markdown、LaTeX、reStructuredText等几十种格式也能写出同等级别。但它是Haskell写的在Python项目里要调它还得用subprocess启动一个子进程很别扭。而且Pandoc的扩展机制是基于滤镜的跟Python Markdown的Python-native扩展比起来开发体验差很多。说回Python Markdown它最打动我的是社区生态。PyPI上有上百个第三方扩展从emoji支持到LaTeX数学公式基本够用了。而且代码质量总体不错维护了十多年稳定性有保障。但也要承认它确实有点驮。如果哪天有人写出一个标准CommonMark支持好、扩展机制灵活、速度快的纯Python Markdown解析器说不定我就换过去了。可惜现在还没有这样一个完美的方案。折腾了这么多年我用Markdown处理文档的态度是这样的先用Python Markdown快速搭个原型确认功能OK了如果性能不够再换。大多数场景根本到不了性能瓶颈这一步。与其纠结用什么工具不如定下来认真写文档。毕竟再好的工具也救不了糟糕的内容你说呢