python markdown

# Python Markdown 那些事：一个老程序员的自用笔记

记得刚接触Python Markdown那会儿，正赶上要给项目写文档。团队里有人用Sphinx，有人用Jupyter，吵得不可开交。最后我默默掏出Python Markdown写了份技术手册，三页纸解决了问题。这不是说别的工具不好，而是我发现，很多时候我们需要的不是一把瑞士军刀，而是一把趁手的小刀。

一、它到底是什么

说白了吧，Python Markdown就是一个能把Markdown文本转换成HTML的Python库。听起来简单得不能再简单了对吧？但就像炒青菜，人人都会，可火候、油温、下锅的时机不同，味道天差地别。

核心就两个东西：一个解析器把Markdown语法吃掉，吐出一棵语法树；然后一个渲染器把这棵树转成HTML。代码层面看，大概长这样：

importmarkdown text="# 标题"html=markdown.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里加一句：

<linkrel="stylesheet"href="https://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.tag='blockquote'para.text=para.text[3:]

这招儿很管用。有次客户要求所有包含"NEXT"字样的段落要特别标记，我没改Markdown源文件，就靠这个扩展在渲染时偷偷替换。

四、一些实战经验

1. 缓存是王道。别每次请求都重新解析Markdown。特别是大文档，解析很费时间。加个lru_cache装饰器，或者用Redis存一下渲染结果，性能能翻个十倍。

2. 安全这块要当心。默认设置下，Python Markdown会把用户输入的Markdown里的HTML标签原样输出。这就埋了XSS的雷。如果用户能输入内容，记得这样：

importbleach html=markdown.markdown(user_input)safe_html=bleach.clean(html,tags=['p','h1','h2','em','strong','a'],attributes={'a':['href','title']})

不放心的话，还有更深的口子：允许的标签列表最好白名单限制死。

3. 目录生成有技巧。toc扩展生成的目录默认插在文档开头。但有时候想把它放在侧栏，可以这样：

md=markdown.Markdown(extensions=['toc'])html=md.convert(md_text)toc=md.toc# 这玩意儿是HTML字符串

然后就可以自己决定把toc放在页面的哪个位置了。比如写个很简陋的双栏布局：

<divstyle="display:flex;"><divstyle="width:20%;border-right:1px solid #eee;">{{ toc | safe }}</div><divstyle="width:80%;padding-left:20px;">{{ content | safe }}</div></div>

4. 性能调优。纯Python写的东西，解析速度当然拼不过C写的库。但如果只是几百行的文档，差别几乎感觉不出来。真的遇到超大文档（比如系统生成的API文档有上千个接口），可以考虑用进程池并行解析。原因很简单：Python Markdown解析时受GIL影响，多线程帮不上忙，但多进程能解决。

fromconcurrent.futuresimportProcessPoolExecutordefrender_chunk(chunk):returnmarkdown.markdown(chunk,extensions=EXTENSIONS)withProcessPoolExecutor(max_workers=4)asexecutor:results=list(executor.map(render_chunk,big_doc_chunks))full_html=''.join(results)

5. 调试技巧。有时候生成的HTML不对劲，别急着改配置。先把markdown.markdown(text, output_format='debug')跑一下，看看解析器是怎么理解你的Markdown的。这个选项会输出一棵AST，一眼就能看出是语法写错了还是解析器理解错了。

五、同类技术的比较

市面上常见的Markdown解析器有几个：

• md4c：C语言实现，速度快得吓人。很多编辑器（像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 markdown=create_markdown()html=markdown(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了，如果性能不够再换。大多数场景根本到不了性能瓶颈这一步。与其纠结用什么工具，不如定下来认真写文档。毕竟再好的工具也救不了糟糕的内容，你说呢？