企业官网建设流程全解析

• 开发工具

导读

本文以 Jupytext 仓库中一份真实的 ipynb → Markdown 转换产物convert_to_py_then_test_with_update83.md为主线，逐行拆解 Jupytext 的 Markdown 笔记本格式（YAML 头部、代码单元围栏、Markdown 单元、magic 命令与空单元的表达方式），并深入其源码与测试体系，说明这类.md文件是如何通过"镜像测试"（mirror test）和--test/--test-strict往返校验来保证与原始.ipynb语义等价、可双向转换的。读完本文，你将掌握 Jupytext Markdown 格式的完整语法规则，以及如何用命令行与测试工具验证你自己的笔记本在文本格式与 ipynb 之间稳定往返。

一、这份文档是什么：一份转换镜像文件

本文分析的关联文档 convert_to_py_then_test_with_update83.md 位于测试数据目录tests/data/notebooks/outputs/ipynb_to_md/下，它并不是一篇普通的技术说明，而是 Jupytext 测试体系中一个**"镜像文件"（mirror file）——即由输入笔记本 convert_to_py_then_test_with_update83.ipynb 转换为 Markdown 格式后的基准快照**。该目录中与之一一对应的 57 个.md文件（如cat_variable.md、frozen_cell.md、plotly_graphs.md等）组成了 ipynb → md 方向转换的参考输出集。

因此，这份文档的"正文"就是 Jupytext Markdown 笔记本格式的一个真实、完整的示例，它本身就是技术事实的载体。其完整内容如下：

--- jupyter: kernelspec: display_name: Python 3 language: python name: python3 --- ```python %%time print('asdf')

Thanks for jupytext!

与之对应的输入笔记本 [convert_to_py_then_test_with_update83.ipynb](https://link.gitcode.com/i/4d3250a944ac855f7c6f42113fe4de30) 包含三个单元： 1. 一个带 `%%time` magic 的代码单元（执行计数为 1，输出中包含 `asdf` 与 `CPU times: ... Wall time: 188 µs` 计时信息）； 2. 一个内容为 `Thanks for jupytext!` 的 Markdown 单元； 3. 一个 `source` 为空、元数据含 `collapsed: true` 的空代码单元。 将二者对照，即可完整还原 Jupytext 的 Markdown 格式映射规则——这也是本文后续逐节讲解的主线。 ## 二、Jupytext Markdown 格式：三种单元的一一映射 Jupytext 的 Markdown 格式（CLI 中写作 `md`）遵循"**Markdown 单元写成普通 Markdown、代码单元写成围栏代码块**"的直观约定，使得笔记本可以直接用任何 Markdown 编辑器阅读与编辑。从上面的镜像文件可以归纳出三条核心映射规则。 ### 2.1 代码单元 → fenced code block 输入笔记本中的第一个代码单元： ```json { "cell_type": "code", "source": ["%%time\n", "\n", "print('asdf')"], "execution_count": 1, "outputs": [{ "name": "stdout", "output_type": "stream", "text": ["asdf\n", "CPU times: ...\n", "Wall time: 188 µs\n"] }] }

被转换为 md 中的围栏代码块：

```python %%time print('asdf') ```

映射要点：

• 语言标记：围栏起始行```python中的语言名来自笔记本的kernelspec.language元数据（此处为python）。Jupytext 据此判断这是代码单元而非普通 Markdown 文本。
• 源码原样保留：%%time这一 IPython cell magic 行、其后空行与print('asdf')被逐字节保留，说明 Jupytext 的 md 格式对单元内行级结构（含空行）是保真的。
• 输出与执行信息不写入文本：execution_count、outputs等运行期状态只存在于 ipynb 中，md 文本里没有对应痕迹——这正是文本格式适合版本控制的原因：diff 里不会出现大段输出噪声。

2.2 Markdown 单元 → 普通 Markdown 文本

输入中的第二个单元是纯 Markdown 单元（cell_type: "markdown"，source 为Thanks for jupytext!），转换后直接以普通段落形式出现在两个代码围栏之间：

Thanks for jupytext!

这是 Jupytext md 格式最自然的特性：Markdown 单元在文本文件中就是它本身，阅读 .md 版本与阅读最终渲染结果几乎一致。

2.3 空代码单元 → 空围栏代码块

输入中第三个单元source: []（一个空代码单元，元数据collapsed: true），转换后成为一个内容为空的围栏：

```python ```

注意其语言标记python仍被保留。这意味着 Jupytext 能够区分"空代码单元"与"根本不存在单元"，空围栏是维持单元数与单元顺序（roundtrip 保真）的关键手段。在 tests/functional/others/test_preserve_empty_cells.py 一类的测试中，空单元的保留是被专门验证的行为。

三、YAML 头部：kernelspec 与笔记本元数据的载体

镜像文件的最顶部是 Jupytext Markdown 笔记本格式的另一个标志性结构——YAML front matter：

--- jupyter: kernelspec: display_name: Python 3 language: python name: python3 ---

3.1 YAML 头部承载哪些元数据

这里jupyter键下嵌套的kernelspec信息（display_name、language、name）直接来自输入 ipynb 的顶层metadata.kernelspec。当将 md 转回 ipynb 时，这些信息会被还原到笔记本的 metadata 中，从而保持内核选择不变。除了 kernelspec，Jupytext 的 md 头部还会承载其他可序列化的笔记本级元数据（例如jupytext.text_representation中的格式说明），凡是无法用 Markdown 语法表达的元数据都会被收敛进 YAML 头部，实现"文本可见、结构可往返"。

3.2 头部如何参与格式自动识别

YAML 头部不仅是元数据容器，也是 Jupytext 判断文件格式的重要线索。在 src/jupytext/formats.py 中，guess_format一类的逻辑会结合扩展名与内容特征来推断格式：带有jupyter:头部键的.md文件会被识别为 Jupytext Markdown 笔记本，而缺少该头部的普通.md文件则按普通 Markdown 处理。这一区分正是 tests/functional/round_trip/test_mirror.py 中test_myst_file_has_myst_format等测试所覆盖的行为：jupytext.guess_format(text, ".md")能根据头部内容返回("myst", {})或相应的 md 格式标识。

四、源码级验证：这份 md 文件如何被"镜像测试"守护

上文提到该文件位于outputs/ipynb_to_md/，其生成与校验逻辑在仓库中有明确的源码支撑。理解它有助于读者判断这份文档的价值：它不是手工抄写，而是受回归测试保护的格式基准。

4.1 测试入口：test_mirror.py 中的 ipynb → md 方向

tests/functional/round_trip/test_mirror.py 的模块说明写道：这里"生成 py、Rmd 和 ipynb 文件的镜像表示，并确保这些表示在新版本中几乎不变"。其中 ipynb → md 方向的关键一行是：

def test_ipynb_to_md(ipynb_file, no_jupytext_version_number): assert_conversion_same_as_mirror(ipynb_file, "md", "ipynb_to_md")

该测试的参数化 fixture 会遍历tests/data/notebooks/inputs/ipynb_*下的所有输入笔记本（见 tests/conftest.py 中基于SAMPLE_NOTEBOOK_PATH的list_notebooks扫描逻辑），其中就包括本文的输入 convert_to_py_then_test_with_update83.ipynb。

4.2 镜像校验的底层实现

assert_conversion_same_as_mirror定义于 src/jupytext/compare.py，其核心流程为：

1. 读取输入笔记本read(nb_file, fmt=fmt)，解析格式long_form_one_format，必要时用笔记本元数据修正扩展名（check_auto_ext）；
2. 计算镜像文件路径（dirname/../../outputs/<mirror_name>/<file_name><ext>，即本文文件所在的ipynb_to_md目录）；
3. 若镜像文件缺失，则调用create_mirror_file_if_missing（见 compare.py）现场生成——这正是outputs/目录中快照文件的来源机制；
4. 用writes(notebook, fmt)重新序列化当前笔记本，并与其保存的镜像文本逐字节比较，不一致即测试失败。

由此可见，ipynb_to_md/目录中的每一个.md文件都是"当前版本 Jupytext 对 ipynb → md 转换的确定性输出"，任何会改变格式输出的代码改动都会在测试中被捕获。这也解释了为什么该文件包含%%time、空单元、kernelspec 头部这些"边缘但必须稳定"的要素。

4.3 输出与输入的取舍：为何镜像不含 output

细心的读者会发现：输入 ipynb 的第一个代码单元明明带有stdout输出（asdf与CPU times），但 md 镜像中并没有它们。这不是丢失，而是 Jupytext 文本格式的设计决策——文本表示只携带"可编辑内容"（源码、Markdown、元数据），运行产物（outputs、execution_count）留在 ipynb 侧。--test的往返验证也因此聚焦于内容等价而非运行状态等价。若需要在往返过程中把输出合并回文本，可在测试/转换时使用 src/jupytext/combine.py 中combine_inputs_with_outputs一类的能力（见 compare.py 中if update: round_trip = combine_inputs_with_outputs(...)的分支）。

五、命令行实战：转换、往返测试与严格校验

掌握了格式映射后，读者完全可以在本地用 Jupytext CLI 复现这份镜像文件，并对自己的笔记本执行同样的质量校验。相关命令参数均定义在 src/jupytext/cli.py 中。

5.1 用--to md生成 Markdown 笔记本

将任意.ipynb转换为 Jupytext Markdown 格式：

jupytext convert_to_py_then_test_with_update83.ipynb --to md

--to参数接受格式标识或扩展名组合（见 cli.py 的参数说明）：md表示 Jupytext Markdown 格式；md:myst表示 MyST Markdown；也可以写脚本类格式如py:percent、py:light。当使用--to md且未显式给定输出文件名时，会在同目录生成同名的.md文件——这正是 outputs/ipynb_to_md/convert_to_py_then_test_with_update83.md 这类快照文件的日常生成方式。

5.2 用--test/--test-strict验证往返稳定性

文本格式与 ipynb 能否无损互转，是 Jupytext 承诺的核心。CLI 提供了两个级别的往返测试（见 cli.py）：

# 常规往返测试：允许"预期的差异"（如格式相关的规范化） jupytext notebook.md --test # 严格往返测试：要求文本 ↔ ipynb 完全一致 jupytext notebook.md --test-strict

参数说明原文为：

• --test：测试笔记本在往返转换下保持稳定，允许存在预期内的变化；
• --test-strict：测试笔记本在往返转换下严格稳定。

二者底层都走 compare.py 的test_round_trip_conversion：先writes得到文本，再reads读回，最后用compare_notebooks逐单元比对；当update为真时还会先combine_inputs_with_outputs把输出合并回来再比较。compare_notebooks（见 compare.py）会报告"第几个单元的输出不同"或"多出了额外单元"，并以NotebookDifference异常抛出首个差异。

配合-x/--stop（见 cli.py）可以在遇到第一个往返错误时立即停止并打印堆栈，便于在批量校验中快速定位问题：

jupytext notebook.md --test --stop

另外，--check-source-is-newer（见 cli.py）与-w/--warn-only（见 cli.py）可用于配对文件场景下"确认源文件最新"和"失败仅告警继续处理"的 CI 场景。

5.3 手动验证这份镜像文件

以本文关联文档为例，可自行验证"ipynb → md"方向的一致性：

# 1. 用输入 ipynb 现场生成 md 并比较差异 jupytext tests/data/notebooks/inputs/ipynb_py/convert_to_py_then_test_with_update83.ipynb --to md --output /tmp/out.md diff /tmp/out.md tests/data/notebooks/outputs/ipynb_to_md/convert_to_py_then_test_with_update83.md # 2. 对 md 镜像执行往返测试，确认可无损读回 jupytext tests/data/notebooks/outputs/ipynb_to_md/convert_to_py_then_test_with_update83.md --test

若diff无输出，说明当前版本的 Jupytext 转换结果与仓库中的基准快照完全一致；若--test通过，说明这份 md 文件读回 ipynb 后与原笔记本内容等价。

六、进一步探索：关联的格式族与测试矩阵

这份镜像文件所在的outputs/ipynb_to_md/只是 Jupytext 庞大测试矩阵的一角。同一输入集还对应着ipynb_to_Rmd/、ipynb_to_myst/、ipynb_to_percent/、ipynb_to_marimo/等方向，在 test_mirror.py 中分别由test_ipynb_to_Rmd、test_ipynb_to_myst、test_ipynb_to_percent、test_ipynb_to_marimo（后者需本机安装 marimo，见@pytest.mark.requires_marimo）等测试守护；反向方向则由test_md_to_ipynb、test_myst_to_ipynb等覆盖。这些测试共同回答同一个问题：任一种文本格式都能与 ipynb 双向无损往返。

若想深入格式细节，建议按以下路径阅读：

• 格式定义与格式名解析：src/jupytext/formats.py（guess_format、long_form_one_format、check_auto_ext）；
• Markdown 格式的读写实现：src/jupytext/myst.py 与 src/jupytext/pandoc.py（md / myst 相关），代码单元与 Markdown 单元的分割逻辑主要在 src/jupytext/cell_reader.py；
• 单元元数据过滤规则：src/jupytext/metadata_filter.py，以及对应的测试 tests/functional/metadata/test_metadata_filter.py；
• 往返测试夹具与镜像机制：tests/conftest.py（SAMPLE_NOTEBOOK_PATH、list_notebooks、no_jupytext_version_numberfixture）与 src/jupytext/compare.py。

结语

convert_to_py_then_test_with_update83.md虽只有十几行，却是观察 Jupytext 设计哲学的绝佳样本：它同时展示了 Markdown 笔记本格式的三种单元映射、YAML 头部的元数据承载、以及"输出不进文本"的取舍；而它在测试目录中的位置，又把它与test_mirror.py、compare.py的镜像校验机制、CLI 的--to/--test/--test-strict命令串联成一条完整的技术链路。理解这份文件，就等于理解了 Jupytext 如何让笔记本以 Markdown 形态进入版本控制，同时保证与 ipynb 之间的双向无损往返。

• 开发工具