Brython 的 browser.markdown 模块:在浏览器中把 Markdown 渲染为 HTML 并执行内嵌 Python 脚本

原创2026-10-07 22:26:511,349 阅读
文章标签:编程语言语言运行时编译器前端

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 场景做了两项关键适配:

  1. 渲染结果可直接写入页面元素:mark() 返回的 HTML 字符串可直接赋值给 document['xxx'].html。
  2. 脚本代码与页面分离:渲染时不会把 <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>,其中下划线会被转义为 &#95; 以防被误判为强调标记。

也就是说,开发者可以用 ```python、```exec、```python-console 等写法为不同代码块打上语义标签,随后在浏览器端用 CSS 或 document.select('.exec') 等手段精准定位处理。

核心 API:mark(src) 函数

模块对外暴露的核心函数是 mark(),文档给出了明确签名与返回值约定:

mark(src)
  • 参数 src:一个包含 Markdown 格式化文本的字符串;
  • 返回值:一个二元元组 (html, scripts):
    • html:由源文本生成的 HTML 代码字符串;
    • scripts:一个数组/列表,包含页面中所有脚本的源码。

从 mark() 的实现 看,处理流程大致分为两阶段:

  1. 行级预处理:把源文本按行切分,依次识别并生成块级结构——> 开头的引用块(<blockquote>)、-/+/* 开头的无序列表(<ul>/<li>,支持缩进嵌套)、1. 开头的有序列表(<ol>)、# 开头的标题(<H1>~<H6>)、---/=== 下划线式标题、以 4 个空格缩进的代码块、``` 围栏代码块,以及 <script> 脚本段。
  2. 内联格式化:对普通文本段落调用 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 位随机字符串临时替换标签,完成强调处理后再恢复;< 后同一行内无 > 时按"小于号"处理,转义为 &lt;。
  • 内联代码:反引号 `code` 内的 <、>、&、_ 会被转义(escape()),避免代码片段被误渲染;转义的反引号 \`` 输出为 ``。
  • 转义字符:\_、\* 分别输出 &#95;、&#42;,允许作者在正文中写出字面量下划线或星号。
  • 脚本提取:<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() 用法与源码级渲染规则结合起来,即可快速落地一套完整方案。

登录后查看全文
brython