企业官网建设流程全解析

• 开发工具

Jupytext 的核心能力之一，是让同一个 Notebook 既能以.ipynb（JSON）保存，也能以 Markdown、脚本等文本格式存在，并且两者可无损互转。本文以仓库中的真实样例jupyterlab-slideshow_1441为骨架，逐层剖析 Jupyter Notebook 中那些"复杂 JSON 单元格元数据"——包括 JupyterLab 幻灯片演示（jupyterlab-slideshow）与字体覆盖（@deathbeds/jupyterlab-fonts）——是如何被序列化进 Markdown 文本、又如何在读取时被还原回cell.metadata的。读完本文，你将掌握 Jupytext 的 HTML region 注释语法、key=value与 JSON 两种元数据编码的判别规则，以及#region/#endregion标记在源码中的完整读写链路。

一、样例文档全景：一页 Markdown 背后藏着一整套元数据协议

仓库中用于测试该场景的输出文档位于 tests/data/notebooks/outputs/ipynb_to_md/jupyterlab-slideshow_1441.md，全文仅 13 行，却完整演示了 Jupytext Markdown 格式承载复杂单元格元数据的标准写法：

--- jupyter: kernelspec: display_name: Python 3 (ipykernel) language: python name: python3 --- <!-- #region @deathbeds/jupyterlab-fonts={"styles": {"": {"body[data-jp-deck-mode='presenting'] &": {"right": "0", "top": "30%", "width": "25%", "z-index": 1}}}} jupyterlab-slideshow={"layer": "slide"} --> > **Note** > > `slide` layer with a `top` of `30%` <!-- #endregion -->

这份文档由三部分构成，三者合起来才是一个完整的 Markdown 版 Notebook：

1. Jupyter 元数据头（YAML front matter）：---包裹的jupyter.kernelspec，记录了内核的display_name、language与name。这是文本 Notebook 的"文档级元数据"，对应.ipynb中的顶层metadata.kernelspec。
2. 单元格开始标记（HTML 注释形式的#region）：<!-- #region ... -->是 Markdown 格式下单元格的边界，#region后的空格起便是该单元格的元数据。
3. 单元格内容与结束标记：正文是一段引用块> **Note**，随后的<!-- #endregion -->明确划定了单元格的结束位置。

注意这段元数据里同时出现了两个复杂 JSON 对象：@deathbeds/jupyterlab-fonts（一个包含 CSS 选择器body[data-jp-deck-mode='presenting'] &的嵌套styles结构）和jupyterlab-slideshow（值为{"layer": "slide"}）。它们都是嵌套字典，无法用简单的key=value表示，这正是本文要重点讨论的 JSON 元数据编码场景。

二、源头 .ipynb：这些元数据从哪来、长什么样

Markdown 版本并非凭空生成，它对应的是 tests/data/notebooks/inputs/ipynb_py/jupyterlab-slideshow_1441.ipynb 中的同一个单元格。在该.ipynb里，单元格metadata结构如下：

{ "cell_type": "markdown", "id": "7f0da6ff-9da5-453c-8515-88fabeb03582", "metadata": { "@deathbeds/jupyterlab-fonts": { "styles": { "": { "body[data-jp-deck-mode='presenting'] &": { "right": "0", "top": "30%", "width": "25%", "z-index": 1 } } } }, "jupyterlab-slideshow": { "layer": "slide" } }, "source": [ "> **Note**\n", "> \n", "> `slide` layer with a `top` of `30%`" ] }

其中jupyterlab-slideshow是 JupyterLab 官方幻灯片扩展使用的元数据，layer字段取值为slide（此外还常见sub-slide、fragment、skip、notes等），决定该单元格在演示模式中属于哪一层；@deathbeds/jupyterlab-fonts则是@deathbeds/jupyterlab-fonts扩展的配置，此处用一条 CSS 选择器body[data-jp-deck-mode='presenting'] &在演示模式下把该单元格定位到页面右上角（right: 0; top: 30%），并控制宽度为25%、层叠层级z-index: 1。单元格正文是一段引用块，内容与上面的 Markdown 完全对应。

可以确认：Jupytext 在ipynb → md转换时，对这类嵌套 JSON 元数据不是丢弃，而是整体原样搬进文本表示，从而保证往返转换不丢失信息。

三、HTML region 注释：Jupytext Markdown 单元格边界的语法核心

<!-- #region ... -->与<!-- #endregion -->并非普通 Markdown 内容，而是 Jupytext 定义的单元格边界标记。其语法在源码 src/jupytext/cell_reader.py 中有精确的权威定义：

start_region_re = re.compile(r"^<!--\s*#(region|markdown|md|raw)(.*)-->\s*$")

即一个合法的 region 开始行必须满足：以<!--开头、可选的空白、#后跟region/markdown/md/raw四种类型名之一、随后是"任意剩余内容"（(.*)，即元数据区）、再以-->收尾。四种类型名的含义分别是：

• region：普通 markdown 单元格；
• markdown/md：显式声明该 region 为 markdown 单元格（等价于region_name元数据）；
• raw：声明为 raw 单元格。

读取时（cell_reader.py），匹配到开始标记后 Jupytext 会记录当前region_name，动态生成对应的结束标记正则^<!--\s*#end{region_name}\s*-->（例如#endregion、#endmarkdown、#endraw），并把#region后的内容交给text_to_metadata解析出title与metadata字典；直到遇到#endregion行才认定该单元格结束（cell_reader.py）。

写出的方向则相反。在 src/jupytext/cell_to_text.py 的html_comment方法中，Jupytext 会根据单元格是否有标题、是否有元数据来决定 region 开始行的形态：

def html_comment(self, metadata, code="region"): ... region_start = " ".join(region_start) region_start = f"<!-- #{code} -->" ... return [region_start] + self.source + [f"<!-- #end{code} -->"]

有元数据时，开始行形如<!-- #region <序列化后的元数据> -->；无元数据时则退化为最朴素的<!-- #region -->。两者都以<!-- #endregion -->结束。

四、JSON vs key=value：元数据编码方式如何被自动判别

示例文档中 region 行内的元数据同时包含两个嵌套 JSON 对象，它走的是JSON 元数据编码路径。Jupytext 判断一行元数据应采用 JSON 编码还是key=value编码，依赖 src/jupytext/cell_metadata.py 中的is_json_metadata：

def is_json_metadata(text): """Is this a JSON metadata?""" first_curly_bracket = text.find("{") if first_curly_bracket < 0: return False first_equal_sign = text.find("=") if first_equal_sign < 0: return True return first_curly_bracket < first_equal_sign

判据非常直观：如果一行文本中第一个{出现在第一个=之前（或根本没有=），就按 JSON 处理；否则按key=value处理。在样例中，@deathbeds/jupyterlab-fonts={...} jupyterlab-slideshow={...}这一行的第一个字符就是@开头的键，其后的{远早于任何=，因此被判定为 JSON 编码。

is_json_metadata的调用点同时覆盖读取端与写出端：

• 读取端（cell_reader.py）：对 region 行调用is_json_metadata并据此选择 JSON 或key=value解析；
• 写出端（cell_to_text.py）：根据单元格metadata是否包含嵌套结构，决定采用html_comment的 JSON 写法还是普通写法。

解析 JSON 编码时，cell_metadata.py 的text_to_metadata会先截取第一个{之前的内容作为语言或标题，再把从{开始的剩余部分交给relax_json_loads（cell_metadata.py）做"宽容 JSON 解析"：优先用标准json.loads，失败则回退到ast.literal_eval，从而容忍反引号、单引号等 Markdown 友好写法。序列化方向则由metadata_to_text（cell_metadata.py）负责：当plain_json为真时，整个字典直接用json.dumps压缩成单行，这正是示例文档中@deathbeds/jupyterlab-fonts={"styles": {"": {...}}}这种紧凑形态的来源；否则普通元数据会展开成key=json.dumps(value)的多个键值对。

五、同一元数据，四种文本格式的四种表达

Jupytext 的元数据序列化不是 Markdown 专属，同一份jupyterlab-slideshow元数据在不同文本格式下会呈现不同的语法，仓库的测试输出目录为此提供了完整的对照素材：

以 MyST 版本 outputs/ipynb_to_myst/jupyterlab-slideshow_1441.md 为例，元数据被写成一行独立的显式 JSON：

+++ {"@deathbeds/jupyterlab-fonts": {"styles": {"": {"body[data-jp-deck-mode='presenting'] &": {"right": "0", "top": "30%", "width": "25%", "z-index": 1}}}}, "jupyterlab-slideshow": {"layer": "slide"}}

而 percent 风格脚本 outputs/ipynb_to_percent/jupyterlab-slideshow_1441.py 则把同一份元数据展开为key=value序列：

# + [markdown] @deathbeds/jupyterlab-fonts={"styles": {"": {"body[data-jp-deck-mode='presenting'] &": {"right": "0", "top": "30%", "width": "25%", "z-index": 1}}}} jupyterlab-slideshow={"layer": "slide"} # > **Note** # > # > `slide` layer with a `top` of `30%`

可以看到，Jupytext 对"一个单元格的多条元数据"统一采用key1=value1 key2=value2的空格分隔约定，其中每个 value 都是json.dumps的单行压缩结果——这保证了任意深度的嵌套结构都能无损往返。这也是parse_key_equal_value（cell_metadata.py）从右向左迭代寻找=、用relax_json_loads反序列化每个值的解析依据。仓库还额外生成了 outputs/ipynb_to_Rmd/jupyterlab-slideshow_1441.Rmd、outputs/ipynb_to_script_vim_folding_markers 与 outputs/ipynb_to_script_vscode_folding_markers 等多个派生版本，进一步验证了该元数据在各格式间的等价性。

六、幻灯片元数据在 JupyterLab 中的实际语义

回到业务层面，jupyterlab-slideshow={"layer": "slide"}是 JupyterLab 内置演示功能（deck mode，对应data-jp-deck-mode属性）读取的单元格级配置。当你在 JupyterLab 中按下演示快捷键，JupyterLab 会依据每个单元格的layer决定其出场方式：slide表示该单元格作为一张独立幻灯片的主内容，sub-slide表示从属子页，fragment表示逐条碎片出现，skip表示演示中跳过，notes表示演讲备注。

示例中@deathbeds/jupyterlab-fonts的 CSS 片段正是配合演示场景使用的：选择器body[data-jp-deck-mode='presenting'] &只在"正在演示"时生效，把该单元格固定到视口top: 30%、right: 0的位置，宽度收窄为25%——典型地用于在幻灯片一角放置提示性内容。单元格正文> **Note**与> \slide` layer with a `top` of `30%`` 两行，恰好是对这两个元数据效果的文字说明。

对于使用 Jupytext 的团队，这意味着：只要把.md或.py文本提交进版本库，幻灯片的每层划分、演讲备注、甚至是演示时的样式微调，都会被完整保留。任何人 clone 仓库后，用 Jupytext 把文本转回.ipynb，JupyterLab 中的演示效果与原始 Notebook 完全一致。

七、测试证据：这份样例在仓库中的角色

jupyterlab-slideshow_1441不只是演示素材，它还被纳入仓库的测试体系：

• 在 tests/conftest.py 中，marimo_compatible_ipynbfixture 对该样本执行了显式跳过，注释给出的原因是"contains a line ending with spaces, which is trimmed by marimo"——即该 Notebook 存在以空格结尾的行，而 Marimo 转换器会裁剪行尾空格，属于格式转换差异，而非 Jupytext 自身缺陷。这从侧面印证了本样例以"严格保真"为测试目标：包括行尾空格在内的所有细节都在往返测试的校验范围内。
• 该样本在 tests/conftest.py 的 round-trip 参数化中同样被排除（skip="...|305|jupyterlab-slideshow"），说明它被单独归类处理，避免与其他通用用例混跑。
• 而ipynb_to_md目录下的输出文件本身，就是 Jupytext 测试框架中"输入.ipynb→ 输出文本 → 再读回.ipynb"往返一致性的基准产物。读者可以自行运行jupytext命令复现该转换：

# 将 .ipynb 转为 Markdown 文本 jupytext --to md "tests/data/notebooks/inputs/ipynb_py/jupyterlab-slideshow_1441.ipynb" -o /tmp/slideshow.md # 再将 Markdown 转回 .ipynb，对比元数据是否无损 jupytext --to ipynb /tmp/slideshow.md -o /tmp/slideshow.ipynb

若要在不落盘的情况下比较转换结果，也可以借助 Jupytext 的 Python API（源码入口见 src/jupytext/jupytext.py）：

import jupytext nb = jupytext.read("tests/data/notebooks/inputs/ipynb_py/jupyterlab-slideshow_1441.ipynb") md_text = jupytext.writes(nb, "md") print(md_text) # 检查 region 行中是否保留了 jupyterlab-slideshow 与 @deathbeds/jupyterlab-fonts assert '"layer": "slide"' in md_text assert "jupyterlab-slideshow" in md_text

八、小结：读懂一行 region 注释，就掌握了 Jupytext 的元数据协议

回看样例文档开头的<!-- #region @deathbeds/jupyterlab-fonts={...} jupyterlab-slideshow={"layer": "slide"} -->，这一行里浓缩了 Jupytext 文本格式的三层设计：

1. 边界层：<!-- #region / #endregion -->HTML 注释定义了 Markdown 中单元格的起止，由 cell_reader.py 的正则与 cell_to_text.py 的html_comment共同保证读写对称；
2. 编码层：通过is_json_metadata自动区分 JSON 与key=value两种编码，嵌套结构用json.dumps单行化，解析用relax_json_loads宽容回退（cell_metadata.py）；
3. 语义层：jupyterlab-slideshow.layer与@deathbeds/jupyterlab-fonts.styles等元数据被完整搬运，保证 JupyterLab 幻灯片演示、排版覆盖等能力在文本与.ipynb之间零损耗往返。

因此，当你在版本库中看到一行长而复杂的#region注释时，不必将其视为噪音——那是 Jupytext 为保证"文本即 Notebook"而设计的元数据载体。理解了它的语法与判别规则，你就能从容地手写、审查甚至程序化生成带复杂元数据的 Markdown Notebook，并放心地把 JupyterLab 的演示编排放进 Git 进行协作与评审。

• 开发工具