Brython 浏览器端 Markdown 渲染实战指南:browser.markdown 模块详解
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 解析器不同,这个模块做了两处关键的设计倾斜:
- 面向 Brython 脚本执行:它不仅能渲染文本,还能把页面中的脚本源码单独提取出来,交给调用方(通常是
exec)执行——这让"Markdown 页面里嵌可运行 Python 代码"成为可能。 - 渲染语义微调:它对强调语法做了区分化映射,并保护单词内部的
_不被误解析,细节见下文。
从 模块源码 看,整个模块体积不大,自包含地实现了引用解析、代码块、列表、标题、块引用、链接、图片、行内代码与强调等常用语法,不依赖任何第三方 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()` 把 `_` 统一转为 `_`,最后包进 `<pre class="...">`。这意味着代码块内的 Markdown 标记不会被二次解析,可以安全展示原始代码。
这个 `class` 机制是整个 Brython 生态里"代码块 = 可执行代码"约定的基石:文档页和画廊示例正是通过选择器按 class 定位代码块并触发执行或高亮,详见下文应用章节。
## 核心 API:mark() 函数契约
模块对外只暴露**一个函数**:
```python
mark(src)
参数:src —— 一个以 Markdown 语法格式化的字符串。
返回值:一个 2 元素元组 html, scripts:
html:由src生成的 HTML 代码(字符串);scripts:页面中所有脚本的源代码列表。
这里有一个容易被忽视的要点:scripts 是"源代码列表",而不是"已执行的结果"。调用方拿到这些源码后,需要用 exec() 自行执行。这正是 Brython 把"渲染"与"执行"解耦的设计——渲染器不碰执行环境,执行策略完全由应用决定。
从 源码实现 可以看到 mark() 的完整处理流水线:
- 行尾归一化:把
\r\n替换为\n(L86-L87); - Setext 风格标题:把 "文本行 +
===" 转为<H1>,把 "文本行 +---" 转为<H2>(L89-L91); - 块级结构预处理:以
>开头的行包裹<blockquote>;缩进感知的无序列表(-、+、*)生成嵌套<ul>/<li>;数字.开头的行生成<ol>/<li>(L95-L167); - 分段扫描:把源码切成若干 section,类型包括普通文本段(
Marked)、缩进代码块 / 围栏代码块(CodeBlock)、<script>脚本段(Script)、atx 标题段(H1-H6)、引用定义段(<a href="https://link.gitcode.com/i/4d359921fccfd7ec947d8314af0a72cc" target="_blank">key]: url)([L169-L252); - 逐段渲染并汇总:每个 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())
这段代码的四个动作对应四个明确的职责:
open(url).read():在 Brython 中,open()可以直接读取同源 URL 指向的文本资源(内部走 XHR/fetch桥接,具体可参考 browser.ajax 文档);markdown.mark(...):一次调用完成渲染与脚本提取;document['zone'].html = mk:把 HTML 字符串赋给元素的.html属性完成注入;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` 这类标识符不会被误渲染成斜体;但如果确实需要转义,模块也支持 `\_`、`\*`、`` \` `` 反斜杠转义(分别输出 `_`、`*`、```,见 <a href="https://link.gitcode.com/i/40e87a144e61096c23028c84fec82ac9" target="_blank">markdown.py</a>)。
- **代码块内下划线被转义**:代码块中的 `_` 会被统一替换为 `_` 实体,这是为了避免块内 Markdown 标记干扰,展示代码时浏览器仍会正确显示为 `_`。
- **引用定义缺失会抛异常**:使用 `[text][key]` 引用式链接时,若 `[key]: url` 定义不存在,`mark()` 会抛出 `KeyError`,应用层应做好兜底。
- **跨行 `<` 处理**:一行内 `<` 后没有同行的 `>`,会被当作"小于号"转义为 `<`(<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 内容体系。