Brython 浏览器端 Markdown 渲染实战指南:browser.markdown 模块详解

原创2026-10-06 22:17:031,916 阅读
文章标签:编程语言语言运行时编译器前端

Brython 浏览器端 Markdown 渲染实战指南:browser.markdown 模块详解

导读:browser.markdown 是 Brython 标准库中的浏览器端 Markdown 渲染模块,用于把 Markdown 文本在运行时转换为 HTML,并支持提取页面内嵌脚本加以执行。本文以官方文档为主体,结合 模块源码 和 文档生成脚本 等仓库证据,完整讲解其语法特性、mark() 函数契约、源码内部实现原理以及真实项目中的应用模式,帮助你掌握在浏览器中构建"可编辑、可执行、可发布"的 Markdown 内容体系的完整方案。

Brython(Browser Python)把 Python 3 解释器搬进了浏览器。在它的标准库中,browser.markdown 是一个为"在浏览器里发布带格式文本"而生的轻量 Markdown 渲染模块——它比直接写 HTML 更易编辑,又比通用 Markdown 库更贴近 Brython 的脚本执行场景。本文将基于官方文档 browser.markdown 说明,深入展开这个模块的语法规则、API 契约、源码实现与真实应用案例。

模块定位:为浏览器发布而生的 Markdown 渲染器

Markdown 是一种面向互联网文本发布的格式化方式,比 HTML 更容易手工编辑。browser.markdown 正是围绕这一场景实现的:它接收 Markdown 源文本,输出可在页面中直接插入的 HTML 字符串。

与通用 Markdown 解析器不同,这个模块做了两处关键的设计倾斜:

  1. 面向 Brython 脚本执行:它不仅能渲染文本,还能把页面中的脚本源码单独提取出来,交给调用方(通常是 exec)执行——这让"Markdown 页面里嵌可运行 Python 代码"成为可能。
  2. 渲染语义微调:它对强调语法做了区分化映射,并保护单词内部的 _ 不被误解析,细节见下文。

从 模块源码 看,整个模块体积不大,自包含地实现了引用解析、代码块、列表、标题、块引用、链接、图片、行内代码与强调等常用语法,不依赖任何第三方 JS 库。

与标准 Markdown 的差异:语法渲染微调

官方文档明确列出该模块对标准 Markdown 的三处"改编",目的是丰富渲染选项(enrich the rendering options):

Markdown 语法 映射的 HTML 标签 说明
_text_ 与 *text* <I> 与 <EM> 两种强调写法分别映射到不同标签,而不是都变成 <em>
__text__ 与 **text** <B> 与 <STRONG> 两种加粗写法分别映射到不同标签
单词内部的 _(如 snake_case) 原样保留 不会被解析为强调标记

这组映射在源码中也有对应实现(markdown.py):

  • 加粗通过两条正则完成:r'\*\*(.+?)\*\*' 生成 <STRONG>...</STRONG>,r'__(.+?)__' 生成 <B>...</B>;
  • 斜体通过 r'\*(.+?)\*' 生成 <EM>...</EM>;
  • 单词内部的下划线使用带词边界(\b)的正则 r'\b_(.*?)_\b' 生成 <I>...</I>,因此 my_var 这类标识符中间的 _ 不会被误伤。

围栏代码块:类名即语言

以 ``` 开头、后面跟有文本的行(例如 ```python)会被转换为 <PRE> 元素,跟随的文本成为该元素的 class 名:

```python

会生成 `<pre class="python">...</pre>`。

从源码(<a href="https://link.gitcode.com/i/109f6f11f695406a927be71973c57b98" target="_blank">markdown.py</a>)看,`CodeBlock` 对代码块起始行的处理是:

- ```` ``` ```` 后跟文本 → 以该文本作为 class(`self.info = line[3:]`);
- ```` ``` ```` 后无文本 → 默认 class 为 `"block"`;
- 以 `` ` `` 开头且长度大于 1 的行 → class 为行首反引号之后的内容;
- 以 `>>>` 开头 → class 为 `"python-console"`(交互式控制台代码块);
- 其余 → class 为 `"marked"`。

代码块内容会先经 `escape()` 转义(`&`、`<`、`>`、`_`、`*`),再调用 `unmark()` 把 `_` 统一转为 `&#95;`,最后包进 `<pre class="...">`。这意味着代码块内的 Markdown 标记不会被二次解析,可以安全展示原始代码。

这个 `class` 机制是整个 Brython 生态里"代码块 = 可执行代码"约定的基石:文档页和画廊示例正是通过选择器按 class 定位代码块并触发执行或高亮,详见下文应用章节。

## 核心 API:mark() 函数契约

模块对外只暴露**一个函数**:

```python
mark(src)

参数:src —— 一个以 Markdown 语法格式化的字符串。

返回值:一个 2 元素元组 html, scripts:

  • html:由 src 生成的 HTML 代码(字符串);
  • scripts:页面中所有脚本的源代码列表。

这里有一个容易被忽视的要点:scripts 是"源代码列表",而不是"已执行的结果"。调用方拿到这些源码后,需要用 exec() 自行执行。这正是 Brython 把"渲染"与"执行"解耦的设计——渲染器不碰执行环境,执行策略完全由应用决定。

从 源码实现 可以看到 mark() 的完整处理流水线:

  1. 行尾归一化:把 \r\n 替换为 \n(L86-L87);
  2. Setext 风格标题:把 "文本行 + ===" 转为 <H1>,把 "文本行 + ---" 转为 <H2>(L89-L91);
  3. 块级结构预处理:以 > 开头的行包裹 <blockquote>;缩进感知的无序列表(-、+、*)生成嵌套 <ul>/<li>;数字. 开头的行生成 <ol>/<li>(L95-L167);
  4. 分段扫描:把源码切成若干 section,类型包括普通文本段(Marked)、缩进代码块 / 围栏代码块(CodeBlock)、<script> 脚本段(Script)、atx 标题段(H1-H6)、引用定义段(<a href="https://link.gitcode.com/i/4d359921fccfd7ec947d8314af0a72cc" target="_blank">key]: url)([L169-L252);
  5. 逐段渲染并汇总:每个 section 调用自己的 to_html(),普通文本段再交给 apply_markdown() 做行内语法(链接、图片、行内代码、强调等)处理,最终拼接所有 HTML,汇总所有脚本源码(L254-L260)。

值得注意的实现细节:

  • 引用定义:<a href="https://link.gitcode.com/i/459a051be115a85222465d9562df75e4" target="_blank">key]: url 形式的行会被解析进一个模块级 refs 字典([L72-L73),后续 <a href="https://link.gitcode.com/i/aeb773a61e28dc7e53484a74f9f05de2" target="_blank">text][key] 形式的引用式链接会查表展开;若引用了不存在的 key,会抛出 KeyError('unknown reference ...')([L341-L342)。
  • 链接与图片:text 生成 <a href="url">text</a>,alt 生成 <img src="url" alt="alt">;引用式写法 [text][key] 会解析为对应 <a> 标签。
  • 行内代码与 HTML 隔离:apply_markdown() 在应用 _/* 强调之前,会先把 <...> 形式的 HTML 标签临时替换为随机占位串(rstr),处理完强调后再还原(L350-L358),避免标签属性中的 _、* 被误解析;行内代码 `code` 的内容同样被隔离并转义(&、<、>、_、*),最终生成 <code>...</code>(L407-L431)。
  • HTML 脚本段:以 <script 开头的行会被原样提取为一个 Script 段,其源码进入返回值 scripts 列表,同时从渲染结果中移除(L203-L216)。

官方示例:加载远程 Markdown 并执行脚本

官方文档给出的核心用法如下——从地址 url 读取 Markdown 文件,把生成的 HTML 填入页面区域,并执行所有脚本:

from browser import document, markdown

mk, scripts = markdown.mark(open(url).read())
document['zone'].html = mk
for script in scripts:
    exec(script, globals())

这段代码的四个动作对应四个明确的职责:

  1. open(url).read():在 Brython 中,open() 可以直接读取同源 URL 指向的文本资源(内部走 XHR/fetch 桥接,具体可参考 browser.ajax 文档);
  2. markdown.mark(...):一次调用完成渲染与脚本提取;
  3. document['zone'].html = mk:把 HTML 字符串赋给元素的 .html 属性完成注入;
  4. for script in scripts: exec(script, globals()):逐个执行提取出的脚本源码。

官方文档特别说明:这个技术正是当前这些文档页面本身使用的方案。也就是说,Brython 官网的 Markdown 文档站就是由 browser.markdown 驱动的。

文档站的真实调用链

在 www/doc/docs.py 中可以看到与官方示例几乎一致的实现(L18-L28):

def load(url, target):
    qs = '?foo=%s' % time.time()      # 伪造查询串绕过浏览器缓存
    try:
        mk, scripts = markdown.mark(open(url + qs).read())
    except IOError:
        doc[target].html = "Page %s not found" % url
        return False
    doc[target].html = mk
    for script in scripts:
        exec(script)

注意两处工程化细节:通过 ?foo=<时间戳> 绕过浏览器缓存,以及用 IOError 兜底"页面不存在"的错误提示。随后脚本还做了更多增强(L29-L55):遍历 doc[target].get(selector='.exec') 的代码块,用 browser.highlight 做语法高亮、把代码块设为可编辑、插入"▶"运行按钮并绑定 run() 回调;对 .exec_on_load 的代码块则在页面加载时直接 exec(src);对 .python 代码块只做高亮展示。这完整呈现了"代码块 class 驱动行为"的生态约定:```python → <pre class="python"> → 高亮展示;```exec → <pre class="exec"> → 可编辑 + 一键执行。

其他真实应用场景

仓库中还有多处 browser.markdown 的实战用法:

  • 交互式测试器(www/tests/test_markdown.py):页面放一个 TEXTAREA 作为 Markdown 编辑器,点击后 mk, scripts = markdown.mark(src),把结果渲染进 doc['console'];配合 local_storage 还能在刷新后恢复上一次编辑内容。
  • 画廊转换器(www/gallery/test_markdown.html):一个纯前端 Markdown 转换工具,把文本框中的 Markdown 转成 HTML,同时展示渲染结果(#zone)与原始 HTML 代码(#raw)。
  • 可执行代码演示(www/gallery/markdown_exec.html):构造一段包含 ```exec 代码块的 Markdown,渲染后遍历 .exec 元素,做语法高亮、设为可编辑、插入"▶"按钮,点击按钮时 exec(tg.elt.text.strip(), {}) 执行代码——官方明确表示这种模式可用于在线教程场景。
  • 幻灯片引擎(www/slideshow/en/slideshow.py):body.html = markdown.mark(slideshow.pages[page_num])[0]——连幻灯片翻页内容都是实时用 mark() 渲染的。

完整的浏览器端 Markdown 页面示例

把官方示例扩展成一个可直接运行的最小页面:页面加载时读取同目录的 Markdown 文件并渲染,同时让代码块可以一键执行。

<!doctype html>
<html>
<head>
<meta charset="utf-8">
<script type="text/javascript" src="/src/brython.js"></script>
</head>
<body onLoad="brython()">
<div id="zone"></div>
<script type="text/python">
from browser import document, markdown

def run(ev):
    # 按钮后的元素存有源码
    elt = ev.target.parent.children[ev.target.parent.children.index(ev.target) + 1]
    exec(elt.text, {})

mk, scripts = markdown.mark(open('page.md').read())
document['zone'].html = mk

for elt in document.select('.exec'):
    btn = document.createElement('button')
    btn.text = '▶'
    btn.bind('click', run)
    elt.parent.insertBefore(btn, elt)
</script>
</body>
</html>

其中 page.md 的内容可以包含:

# 标题

这是一段 **加粗**、*斜体* 和 `code` 混合的文本,
以及 [一个链接](https://example.com)。

```exec
from browser import alert
alert("hello")
  • 列表项一
  • 列表项二

渲染后:标题变成 `<H1>`,强调按文档规则映射为 `<B>/<I>`,` ```exec ` 代码块变成 `<pre class="exec">`,随后页面脚本为每个 `.exec` 块加上"▶"按钮,点击即执行其中的 Python 代码。

## 常见问题与注意事项

- **脚本不会被自动执行**:`mark()` 只负责提取脚本源码并放进返回值,执行权在调用方。若忘记遍历 `scripts` 调用 `exec`,页面里嵌入的代码块只是"好看的静态文本"。
- **单词内下划线安全**:得益于 `\b_(.*?)_\b` 的正则设计,`user_name`、`my_var` 这类标识符不会被误渲染成斜体;但如果确实需要转义,模块也支持 `\_`、`\*`、`` \` `` 反斜杠转义(分别输出 `&#95;`、`&#42;`、`&#96;`,见 <a href="https://link.gitcode.com/i/40e87a144e61096c23028c84fec82ac9" target="_blank">markdown.py</a>)。
- **代码块内下划线被转义**:代码块中的 `_` 会被统一替换为 `&#95;` 实体,这是为了避免块内 Markdown 标记干扰,展示代码时浏览器仍会正确显示为 `_`。
- **引用定义缺失会抛异常**:使用 `[text][key]` 引用式链接时,若 `[key]: url` 定义不存在,`mark()` 会抛出 `KeyError`,应用层应做好兜底。
- **跨行 `<` 处理**:一行内 `<` 后没有同行的 `>`,会被当作"小于号"转义为 `&lt;`(<a href="https://link.gitcode.com/i/8a588d183a2698b7b37fbc33cc053ae3" target="_blank">markdown.py</a>),避免把比较表达式误当 HTML 标签。
- **缓存问题**:通过 `open()` 读取远程 Markdown 时,浏览器缓存可能导致内容不刷新,参考 <a href="https://link.gitcode.com/i/698281f9e02611b01e8209ca47112ddf" target="_blank">docs.py</a> 的做法在 URL 后追加时间戳查询串。

## 小结

`browser.markdown` 用极小的 API 面积(一个 `mark()` 函数)实现了浏览器端 Markdown 的完整闭环:**渲染**(Markdown → HTML)、**提取**(脚本源码收集)、**联动**(`<pre class>` 约定与 `exec` 执行)。围绕它,Brython 仓库生长出了文档站、交互式测试器、在线教程演示、幻灯片引擎等一整套"内容即代码"的应用形态。

若想进一步研究,推荐按以下路径深入仓库:

- 模块官方文档:<a href="https://link.gitcode.com/i/4bf3d33650cadbb33b15b27e051b9f60" target="_blank">www/doc/en/browser.markdown.md</a>(另有 <a href="https://link.gitcode.com/i/3660d50afcc1f60998aa47985558b492" target="_blank">法语版</a>、<a href="https://link.gitcode.com/i/1744fa3e8f4ca5dbf0a41165391255fe" target="_blank">西语版</a>)
- 完整实现源码:<a href="https://link.gitcode.com/i/6786a64b82e16083f655771a7fbe9fa0" target="_blank">www/src/Lib/browser/markdown.py</a>
- 文档站加载器(官方示例的真实落地):<a href="https://link.gitcode.com/i/f85574a0ae483f9fb8d9a7e2f46a9ea3" target="_blank">www/doc/docs.py</a>
- 交互式测试页面:<a href="https://link.gitcode.com/i/9aec1047926b923aebe122815461f2dc" target="_blank">www/tests/test_markdown.py</a>
- 画廊示例(转换器 / 可执行代码):<a href="https://link.gitcode.com/i/afb78e623182cc8bc119564cf26b96fe" target="_blank">www/gallery/test_markdown.html</a>、<a href="https://link.gitcode.com/i/58d7ee40488ec06ab7986bd7033cb595" target="_blank">www/gallery/markdown_exec.html</a>
- 幻灯片引擎用例:<a href="https://link.gitcode.com/i/ad93c5ad416f9dcf5c350e3a81f94bcc" target="_blank">www/slideshow/en/slideshow.py</a>

掌握了 `mark()` 的输入输出契约和"代码块 class + exec"模式,你就可以在自己的 Brython 页面中复刻出可编辑、可执行、可发布的 Markdown 内容体系。
登录后查看全文
brython