Brython 的 browser.markdown 模块:在浏览器中把 Markdown 渲染为 HTML 并执行内嵌 Python 脚本
Brython 的 browser.markdown 模块:在浏览器中把 Markdown 渲染为 HTML 并执行内嵌 Python 脚本
导读
本文围绕 Brython 官方文档 www/doc/fr/browser.markdown.md 展开,系统讲解 browser.markdown 模块的核心能力:它把适合在互联网上发布的 Markdown 文本转换为 HTML 代码,并同时提取页面中所有脚本源码供 Brython 在浏览器内执行。读完本文,你将掌握 mark() 函数的完整用法、该模块与标准 Markdown 语法的差异细节,以及如何基于源码实现与官方示例(文档站点、在线教程)搭建自己的 Markdown 渲染与代码执行方案。
模块定位:为浏览器量身定做的 Markdown 渲染器
在 Brython 中,browser.markdown 是标准库模块(实现位于 www/src/Lib/browser/markdown.py),它提供了一种比 HTML 更简单的文本格式化方式——Markdown,并将其渲染为可直接注入 DOM 的 HTML 字符串。与一般 Markdown 转换器不同,它针对 Brython 场景做了两项关键适配:
- 渲染结果可直接写入页面元素:
mark()返回的 HTML 字符串可直接赋值给document['xxx'].html。 - 脚本代码与页面分离:渲染时不会把
<script>内容混进 HTML,而是单独收集在返回的scripts列表中,便于随后用exec()在 Brython 解释器中执行。
关于 Markdown 语法的完整标准说明,官方文档指向其作者网站(daringfireball.net),但本模块是一份"略有改编"的实现,改编点正是本文接下来要展开的核心内容。
与标准 Markdown 的渲染差异
原文档明确列出了本模块相对标准 Markdown 的四个改编行为,这些差异在 markdown.py 的 apply_markdown 函数 中都有对应的正则与替换逻辑支撑:
| Markdown 写法 | 生成的 HTML 标签 | 语义 | 源码依据 |
|---|---|---|---|
_text_ |
<I> |
斜体(呈现层) | 正则 \b_(.*?)_\b 替换为 <I>\1</I> |
*text* |
<EM> |
强调(语义层) | 正则 \*(.+?)\* 替换为 <EM>\1</EM> |
__text__ |
<B> |
粗体(呈现层) | 正则 __(.+?)__ 替换为 <B>\1</B> |
**text** |
<STRONG> |
重要(语义层) | 正则 \*\*(.+?)\*\* 替换为 <STRONG>\1</STRONG> |
之所以拆成两对标签,是为了让作者能区分"纯视觉加粗/斜体"(I/B)与"语义强调"(EM/STRONG),这在排版要求严格的文档场景中很有价值。
第三个差异尤为重要:单词内部的下划线保持原样,不做转换。源码通过 \b(词边界)限制匹配范围,确保像 snake_case、my_var 这样的标识符在渲染后不会意外变成斜体——这对写代码文档的开发者是刚需。
代码块与围栏语法:<PRE class="xxx"> 机制
文档指出:以 ``` 开头、后跟文本(如 ```python)的行,会被转换为带类名的 <PRE> 元素,例如 <PRE class="python">。
从 CodeBlock 类的实现 可以看到更完整的规则:
```后带语言名时,取其后内容作为info,最终成为class值(如python);```后无内容时,info默认为"block";- 以单个
`开头(且长度大于 1)的行,info取第一个反引号之后的文本; - 以
>>>开头的行会被识别为python-console交互式控制台输出块; - 输出统一为
<pre class="INFO">转义后的内容</pre>,其中下划线会被转义为_以防被误判为强调标记。
也就是说,开发者可以用 ```python、```exec、```python-console 等写法为不同代码块打上语义标签,随后在浏览器端用 CSS 或 document.select('.exec') 等手段精准定位处理。
核心 API:mark(src) 函数
模块对外暴露的核心函数是 mark(),文档给出了明确签名与返回值约定:
mark(src)
- 参数
src:一个包含 Markdown 格式化文本的字符串; - 返回值:一个二元元组
(html, scripts):html:由源文本生成的 HTML 代码字符串;scripts:一个数组/列表,包含页面中所有脚本的源码。
从 mark() 的实现 看,处理流程大致分为两阶段:
- 行级预处理:把源文本按行切分,依次识别并生成块级结构——
>开头的引用块(<blockquote>)、-/+/*开头的无序列表(<ul>/<li>,支持缩进嵌套)、1.开头的有序列表(<ol>)、#开头的标题(<H1>~<H6>)、---/===下划线式标题、以 4 个空格缩进的代码块、```围栏代码块,以及<script>脚本段。 - 内联格式化:对普通文本段落调用
apply_markdown(),处理链接、图片、代码、强调等行内语法(详见下一节)。
另外,mark() 内部会先做两处文本规范化:\r\n 统一替换为 \n;= 或 - 下划线式标题行会被改写为 #/## 形式后再走标题处理逻辑。模块还支持"引用式链接"(reference-style links):形如 [text][key] 与定义行 [key]: url 的配对通过全局字典 refs 解析,若引用未定义会抛出 KeyError。
内联渲染的源码级细节
apply_markdown()(www/src/Lib/browser/markdown.py#L286)负责行内语法,值得关注的实现细节包括:
- 链接与图片:
text转换为<a href="href">text</a>;alt转换为<img src="src" alt="alt">;引用式[text][key]会查表refs生成链接。 - HTML 标签保护:为避免标签内的
_、*被误转换,渲染前会用 16 位随机字符串临时替换标签,完成强调处理后再恢复;<后同一行内无>时按"小于号"处理,转义为<。 - 内联代码:反引号
`code`内的<、>、&、_会被转义(escape()),避免代码片段被误渲染;转义的反引号\`` 输出为``。 - 转义字符:
\_、\*分别输出_、*,允许作者在正文中写出字面量下划线或星号。 - 脚本提取:
<script>开头的整段内容被 Script 类 单独收进scripts列表,不参与 HTML 输出——这正是"渲染与执行分离"的关键。
实战:加载 Markdown 文件并执行页面脚本
原文档给出了完整的实用示例:从地址 url 读取 Markdown 文件内容,将对应 HTML 填入文档区域 zone,并执行页面中所有脚本:
from browser import document
import markdown
mk, scripts = markdown.mark(open(url).read())
document['zone'].html = mk
for script in scripts:
exec(script, globals())
这段代码说明了两点:open(url).read() 在 Brython 中可读取远程文件(配合服务器环境);exec(script, globals()) 让脚本在页面全局命名空间内执行,从而能访问页面其他代码定义的变量与函数。
该技巧正是 Brython 官方文档站点的实际做法:在 www/doc/docs.py 中,load(url, target) 函数调用 markdown.mark(open(url+qs).read()) 得到 (mk, scripts),先把 mk 写入目标元素,再逐个 exec(script);其中 qs 是形如 ?foo=<时间戳> 的伪查询串,用来绕过浏览器缓存。此外,docs.py 还展示了基于渲染结果的二次加工:对 class="exec" 的元素做语法高亮(highlight.highlight)、设为可编辑并附加"▶"运行按钮;对 class="exec_on_load" 的元素在页面加载时直接执行;对 class="python" 的代码块仅做高亮展示。
应用场景:可编辑可执行的在线教程
仓库中的 www/gallery/markdown_exec.html 是这一能力的产品级示范:它在一个 Markdown 字符串里嵌入 ```exec 代码块,渲染后把 scripts 中的代码插入文档;随后遍历 document.select('.exec') 元素,将其设为 contenteditable、做语法高亮、并在旁边插入 "▶" 按钮。用户点击按钮时,通过 exec(tg.elt.text.strip(), {}) 执行可编辑区域内的 Python 代码。
这种"Markdown 撰写 + 代码可编辑 + 一键执行"的模式非常适合在线教程与互动文档:作者用 Markdown 书写讲解,读者可直接修改示例代码并立即看到运行结果。
测试验证
仓库提供 www/tests/test_markdown.py 交互式测试页面:界面包含一个 TEXTAREA 编辑器(内容可用 local_storage 持久化保存),点击运行按钮后调用 markdown.mark(src) 并把返回的 HTML 写入 doc<a href="https://link.gitcode.com/i/3ec2a8c291a6db50e6d99469ebd6aabd" target="_blank">'console']。它既验证了模块在真实浏览器环境中的渲染行为,也可作为开发者调试 Markdown 语法的便捷工具(配套的 [test_markdown.html 提供测试入口)。
小结
browser.markdown 是 Brython 生态中"文档即应用"路线的关键一环:它继承了标准 Markdown 的轻量书写体验,又针对浏览器与 Python 执行场景做了精确定制——语义化强调标签、代码块类名、脚本提取与 exec() 回放。无论是要搭建官方风格的文档站点(参考 www/doc/docs.py),还是制作可交互的在线教程(参考 www/gallery/markdown_exec.html),把本文介绍的 mark() 用法与源码级渲染规则结合起来,即可快速落地一套完整方案。