Python Markdown 扩展:在 Jupyter 的 Markdown 单元格中嵌入并执行内核代码
Python Markdown 扩展:在 Jupyter 的 Markdown 单元格中嵌入并执行内核代码
导读
Python Markdown 是 jupyter_contrib_nbextensions 提供的一款 Jupyter notebook 扩展,它允许你在 Markdown 单元格中直接嵌入 {{ ... }} 形式的代码表达式,并由当前内核在渲染时动态求值、把结果展示在单元格内。本文以官方 readme.md 为骨架,结合 main.js 与 pre_pymarkdown.py 源码,讲解它的核心用法、信任与安全模型、渲染原理、结果缓存机制,以及如何配合 nbconvert 在导出时保留计算结果。读完本文,你将能够用一条语法让 Markdown 单元格"活"起来,并安全地把它接入自己的导出流水线。
一、扩展定位与基本用法
1.1 它解决什么问题
Jupyter notebook 的 Markdown 单元格是静态文本:你写什么就显示什么,无法感知内核中已有的变量。Python Markdown 扩展打破了这种静态性——凡是内核中存在的变量或可求值的表达式,都可以通过 {{ ... }} 双花括号语法嵌入到 Markdown 单元格中,并在渲染时替换为内核返回的结果。
从 python-markdown.yaml 的元数据可以看出它的定位:
Type: IPython Notebook Extension
Name: Python Markdown
Description: Allows embedding Python-code in markdown cells
Link: readme.md
Icon: python-markdown.png
Main: main.js
Preprocessor: pymdpreprocessor.py
Compatibility: 4.x, 5.x
扩展本身对内核语言基本不敏感(agnostic),但由于绝大多数测试都是在 Python 内核上完成的,实际使用中最稳妥的场景仍是 Python。
1.2 最小可运行示例
假设你已在一个代码单元格中执行:
a = 1.23
然后在某个 Markdown 单元格中写下:
a is {{a}}
渲染后,这个 Markdown 单元格会显示为:
a is 1.23
也就是说,{{a}} 中的表达式被真正提交给了内核执行,返回值(这里即变量 a 的字符串形式)被回填进 Markdown 文本中。这为"动态文档"类用法(把计算结果、统计数字、日期等写进说明文字)提供了极大的便利。
二、信任机制:执行代码的前提条件
重要前提:只有"受信任的 notebook(trusted notebook)"才会执行 {{ ... }} 中的代码。
Jupyter 对 notebook 的信任状态以窗口顶部的指示器呈现:
- 看到 对勾(check mark) 表示 notebook 已被信任;
- 看到 问号(untrusted) 表示尚未被信任:
如果处于未信任状态,请通过菜单 File → Trust Notebook 手动信任该 notebook。信任之后,扩展才会在渲染时执行双花括号内的代码。
这一约束在源码中有明确的强制实现。main.js 的 execute_python 函数开头就是一道硬性闸门:
/* never execute code in untrusted notebooks */
if (IPython.notebook.trusted === false ) {
return undefined
}
同时,扩展还会监听 trust_changed.Notebook 事件,通过 set_trusted_indicator 实时切换顶部指示器的图标与提示文案(fa-check 与 fa-question 的切换),并在 $('#save_widget') 中追加一个 notebook-trusted 图标元素,相关样式定义在 main.css。
安全警告(务必阅读)
Caution:如果你信任了一个 notebook,就等于允许它在你笔记本(notebook server)上执行
{{...}}双花括号之间包含的任何代码。
这是一个不可忽视的安全模型:{{ ... }} 中的内容不是"只读取值",而是真正的内核代码执行。因此:
- 不要信任来路不明的
.ipynb文件; - 不要随意打开他人共享的、带有
{{ ... }}内容的笔记本; - 谨慎处理从网络下载的 notebook,信任操作前先检查其中是否存在可疑的
{{ ... }}表达式。
另一个来自官方文档的注意事项是:花括号内的表达式没有大小限制。如果表达式返回了超大数据集(例如整个 DataFrame、巨大的列表或嵌套结构),轻则让浏览器渲染卡死,重则导致更严重的资源问题,即文档所警示的"you might crash your browser"。
三、更多示例与渲染细节
官方 readme 给出了渲染前后的对比截图。渲染前,Markdown 单元格中只有原始的 {{ ... }} 文本:
渲染后,{{ ... }} 被替换为内核返回的结果:
如果原始代码显示为已渲染的 Markdown 输出,请先确认 notebook 处于受信任状态(检查窗口顶部的对勾)。
3.1 可以嵌入哪些内容
从源码的回调处理逻辑(execute_callback)来看,{{ ... }} 的求值结果支持相当丰富的输出类型,main.js 按 msg_type 分派处理:
| 内核消息类型 | 处理方式 |
|---|---|
error |
将异常名与异常值(ename / evalue)拼成 **错误名**: 错误信息 文本,用 marked 渲染为 Markdown |
stream |
对 stdout 文本做 marked 渲染,并剥离 marked 添加的 <p>...</p> 包裹与字符串首尾的引号 |
execute_result / display_data |
按 mime 类型依次择优输出:text/latex → image/svg+xml → image/jpeg → image/png → text/markdown → text/html → text/plain |
| 其他 | 直接忽略(return) |
也就是说,你不仅可以用它输出简单变量,还可以:
- 返回 LaTeX 公式(
text/latex),配合 MathJax 渲染; - 返回 SVG、JPEG、PNG 图片(以 base64 内嵌
<img>标签形式输出,注意官方注释指出 SVG 图片在重新加载时会再次被浏览器安全过滤器清理); - 返回 Markdown 文本(
text/markdown,经 marked 渲染); - 返回任意 HTML(
text/html,原样嵌入); - 返回纯文本(
text/plain,同样做<p>剥离与引号清理)。
这使得 {{ ... }} 可以承担"在文档里动态生成图表、公式与格式化内容"的职责,而不必跳转到代码单元格。
四、工作原理:源码级剖析
官方 readme 的 Internals 一节揭示了实现要点,下面结合 main.js 逐条展开。
4.1 覆写 MarkdownCell 的 render 方法
扩展通过覆写 textcell.MarkdownCell.prototype.render 来介入渲染流程:
var original_render = textcell.MarkdownCell.prototype.render;
textcell.MarkdownCell.prototype.render = function() {
if (IPython.notebook.dirty === true) {
this.rendered = false
}
return original_render.apply(this)
};
这里有一个精妙的设计:当 notebook 处于 dirty(有未保存修改) 状态时,强制把单元格标记为 rendered = false,从而促使后续真正重渲染,避免用户看到过期值。
4.2 execute_python:查找、求值与回填
execute_python 是核心函数,它针对单元格 HTML 内容执行正则替换:
var newtext = text.replace(/{{(.*?)}}/g, function(match,tag,cha) { ... });
对每个匹配到的 {{...}}:
- 生成唯一占位 ID:
'python_' + cell.cell_id + '_' + cha; - 检查
cell.metadata.variables中是否已有缓存值; - 若 notebook 是 dirty 的、或缓存中不存在该表达式的值,则清空缓存并重新执行:
即先插入一个带 ID 的空cell.notebook.kernel.execute(code, callbacks, {silent: false, store_history : false, stop_on_error: false }); return "<span id='"+id+"'></span>";<span>占位符,等内核返回结果后由回调把 HTML 填进该 span; - 若 notebook 干净且缓存命中,则直接把缓存值包进
<span id='...'>返回。
回填动作发生在 execute_callback 中:结果经 marked 渲染 / mime 分派后,写入 thiscell.metadata.variables[thismatch] = html; 并通过 document.getElementById(id).innerHTML = ... 写入页面。
4.3 结果缓存:cell.metadata.variables
官方文档明确指出:求值结果会被保存到 Markdown 单元格的元数据中,即 cell.metadata.variables[varname]。这一点在源码中有多处呼应:
execute_python开头:if (IPython.notebook.dirty === true) delete cell.metadata.variables;—— 一旦 notebook 变脏,缓存即失效;- 写入侧:
cell.metadata.variables[thismatch] = {}与thiscell.metadata.variables[thismatch] = html;; - 读取侧:干净状态下直接用
cell.metadata.variables[tag]渲染。
缓存的收益是双重的:
- 重新加载 notebook 时无需重新执行代码即可显示上次的计算结果(
update_md_cells会在kernel_ready.Kernel/notebook_loaded.Notebook事件中遍历所有带variables元数据的单元格并重渲染); - 它是 nbconvert 导出时取值的数据源(见下文)。
4.4 渲染后的后处理
render_cell 在写入替换后的 HTML 之后还会触发一次 MathJax 排版:
element[0].innerHTML = text;
MathJax.Hub.Queue(["Typeset",MathJax.Hub,element[0]]);
这正是前面提到的 text/latex 输出能被正确显示为公式的原因——即使 {{ ... }} 返回的是 LaTeX 表达式,也会在渲染后被重新排版。
4.5 一个已知的 TODO
源码注释中还记录了一个已知行为限制:
TODO: Markdown cells will only be reevaluated when a notebook is dirty (i.e. you have made changes). If you save it before reevaluating MD cells, they will show the old value.
即:Markdown 单元格只会在 notebook 处于 dirty(有修改)状态时才重新求值;如果在重新求值前就保存了 notebook,单元格会显示旧值。理解这一点有助于避免"为什么更新了变量但 Markdown 没变"的困惑。
五、通过 nbconvert 导出计算结果
Markdown 单元格里的 {{ ... }} 在 notebook 界面中由浏览器端 JS 负责求值,但导出的静态文件(HTML、RST 等)不会执行 JS。为此,官方提供了 nbconvert 预处理器的配套方案。
5.1 官方安装路径下的自动配置
如果你通过 python setup.py install(或 pip 安装 jupyter_contrib_nbextensions 包)完成安装,PyMarkdownPreprocessor 会被自动接入 nbconvert 配置。这一点在 install.py 中有明确证据——安装命令会向 jupyter_nbconvert_config.json 的 Exporter.preprocessors 列表追加:
proc_mod = 'jupyter_contrib_nbextensions.nbconvert_support'
_update_config_list(config, 'Exporter.preprocessors', [
proc_mod + '.CodeFoldingPreprocessor',
proc_mod + '.PyMarkdownPreprocessor',
], install)
同时在 nbconvert_support/init.py 中,PyMarkdownPreprocessor 被作为模块的公开导出项(__all__)提供,因此既可以写全限定名 jupyter_contrib_nbextensions.nbconvert_support.PyMarkdownPreprocessor,也可以直接 from jupyter_contrib_nbextensions.nbconvert_support import PyMarkdownPreprocessor(测试代码使用的正是这个快捷导入,见下文)。官方文档 exporting.rst 与 config.rst 也都列出了该预处理器。
5.2 手动配置
如果无法走安装脚本,可以手动完成两步:
第一步:将 pre_pymarkdown.py 复制到 Python 可搜索路径中的某个位置(或把它的所在目录加入 PYTHONPATH)。
第二步:在 jupyter_nbconvert_config.py 配置文件中加入:
c = get_config()
c.Exporter.preprocessors = ['pre_pymarkdown.PyMarkdownPreprocessor']
之后执行 jupyter nbconvert --to html mynotebook.ipynb(或其他格式)时,导出的文档就会包含 {{ ... }} 对应的计算结果。
5.3 预处理器实现细节
pre_pymarkdown.py 的实现非常简洁:
def replace_variables(self, source, variables):
try:
replaced = re.sub(
"{{(.*?)}}", lambda m: variables.get(m.group(1), ''), source)
except TypeError:
replaced = source
return replaced
def preprocess_cell(self, cell, resources, index):
if cell.cell_type == "markdown":
if hasattr(cell['metadata'], 'variables'):
variables = cell['metadata']['variables']
if len(variables) > 0:
cell.source = self.replace_variables(cell.source, variables)
return cell, resources
它的工作逻辑与前端一致:对每个 markdown 单元格,读取 cell.metadata.variables,用正则 {{(.*?)}} 匹配源码,并用元数据中存储的值替换对应表达式(未找到的表达式替换为空串)。这正是"导出时不再执行内核代码、直接复用缓存结果"的设计——与前端干净状态下的渲染路径完全同源。
5.4 测试验证
仓库测试 test_preprocessors.py 中的 test_preprocessor_pymarkdown 用例验证了这条导出链路:
notebook_node = nbf.new_notebook(cells=[
nbf.new_code_cell(source="a = 'world'"),
nbf.new_markdown_cell(source="Hello {{ a }}",
metadata={"variables": {" a ": "world"}}),
])
body, resources = export_through_preprocessor(
notebook_node, PyMarkdownPreprocessor, RSTExporter, 'rst', )
expected = 'Hello world'
assert_in(expected, body, 'first cell should contain {}'.format(expected))
该测试以 RSTExporter 为例,构建一个带 variables 元数据的 markdown 单元格,经过预处理器后断言导出正文中包含 Hello world。你也可以把它作为自定义导出场景的最小参考实现。
六、已知限制与注意事项
6.1 不支持 LaTeX 导出中的动态求值
官方文档明确声明:
Unfortunately, embedding in LaTeX is not supported currently, as computing expressions between the curly braces and rendering LaTeX equations is happening asynchronously, and it is difficult to handle this in a consistent way.
原因在于:{{ ... }} 的求值与 LaTeX 公式渲染都是异步发生的,二者难以在导出管线中保持一致。因此需要把 {{ ... }} 结果导出为 LaTeX / PDF 时,目前只能依赖单元格元数据中已缓存的值(由预处理器替换),而无法在导出阶段重新触发内核执行。官方欢迎社区通过 issue 或 pull request 完善此功能。
6.2 其他实操提醒
- 先保存再导出:nbconvert 预处理器读取的是单元格元数据缓存,如果 notebook 在最后一次求值后又被修改但未重新渲染/保存,缓存可能与当前内核状态不一致,导出结果自然也是旧值;
- 注意输出体积:
{{ ... }}返回超大对象会造成浏览器与导出文档的双重负担; - 图片会被净化:嵌入的 SVG 等图片在 notebook 重新加载时会被浏览器安全机制清理,若需要稳定展示图片,应优先使用代码单元格 + 内嵌附件的方式。
七、快速上手清单
- 按 安装指南 安装扩展并启用:
pip install jupyter_contrib_nbextensions,随后执行jupyter contrib nbextension install --user; - 在 notebook 中启用该扩展(
jupyter nbextension enable python-markdown/main,或通过 jupyter_nbextensions_configurator 的 nbextensions 面板勾选); - 在代码单元格中定义变量(如
a = 1.23); - 在 Markdown 单元格中写入
a is {{a}}; - 通过菜单 File → Trust Notebook 信任当前 notebook(务必确认 notebook 来源可信);
- 触发 Markdown 单元格渲染,观察
{{ ... }}被替换为计算结果; - 需要导出时,确保
PyMarkdownPreprocessor已配置到jupyter_nbconvert_config.py,再用jupyter nbconvert转换即可在输出文档中保留计算值。
参考文件索引:官方说明 readme.md|前端实现 main.js|元数据声明 python-markdown.yaml|nbconvert 预处理器 pre_pymarkdown.py|导出说明 exporting.rst|配置说明 config.rst|测试用例 test_preprocessors.py|安装脚本 install.py



