开发工具【免费下载链接】jupytextJupyter Notebooks as Markdown Documents, Julia, Python or R scripts项目地址https://gitcode.com/gh_mirrors/ju/jupytext点击查看免费下载Jupytext 的核心能力是把 Jupyter 笔记本.ipynb与纯文本格式Markdown、脚本等相互转换让笔记本可以被 Git 友好地版本管理和协作。本文以仓库测试集中一个最简 SageMath 笔记本sage_print_hello.ipynb为例完整演示并剖析 Sage 笔记本 → Markdown 的转换流程从 YAML 元数据头的生成、代码单元到围栏代码块的映射到命令行与 Python API 两种实操方式再到反向转换与源码级原理验证帮助读者在任意语言内核尤其是 SageMath上快速上手 Jupytext 的文本化工作流。转换产物一瞥输入与输出对照关联文档tests/data/notebooks/outputs/ipynb_to_md/sage_print_hello.md是转换的最终产物内容极简但完整--- jupyter: kernelspec: display_name: SageMath 9.2 language: sage name: sagemath --- sage print(Hello world)其上游输入是 [tests/data/notebooks/inputs/ipynb_sage/sage_print_hello.ipynb](https://link.gitcode.com/i/13380073bd58bf9aea2372d0cca7656e) - 笔记本只有一个 code 类型单元源代码为 print(Hello world)execution_count 为 null、无输出 - 顶层 metadata.kernelspec 声明内核为 SageMath 9.2display_name: SageMath 9.2、language: sage、name: sagemath - language_info 记录 name: python、file_extension: .py、codemirror_mode 为 ipython 3 等——这是 Sage 内核继承自 IPython 环境的典型特征也是下方源码分析中一个关键细节。 对照两张表可以发现**转换并非机械复制单元内容**而是做了三件事剥离执行计数与输出轻量 Markdown 格式只承载代码与元数据、把 kernelspec 元数据重新组织成 Jupytext 的 YAML 元数据头、把代码单元渲染成带语言标签 sage 的 Markdown 围栏代码块。 ## 把 Sage 笔记本变成 Markdown 的两种实操方式 ### 方式一命令行转换CLI 与 README 中 convert a notebook in one format to another with jupytext --to ipynb notebook.py见 [README.md](https://link.gitcode.com/i/4c8680e0fcd27acf9e879b616b6b7020)对应方向反过来即可 bash # 将 Sage 笔记本转换为 Markdown 文本笔记本 jupytext --to md tests/data/notebooks/inputs/ipynb_sage/sage_print_hello.ipynb # 若希望生成独立的指定输出文件使用 -o 指定输出路径 jupytext --to md tests/data/notebooks/inputs/ipynb_sage/sage_print_hello.ipynb -o sage_print_hello.md生成的sage_print_hello.md即与ipynb_to_md目录下的输出一致。--to md中的md对应 Jupytext 的markdown格式format_namemarkdown、extension.md见下文 formats 源码。需要注意在转换命令没有显式加-o时输出文件路径由目标扩展名推导运行时请依据实际工作目录合理组织输入输出避免覆盖同名文件。方式二Python API 调用在 Python 会话中调用同样简单import jupytext nb jupytext.read(tests/data/notebooks/inputs/ipynb_sage/sage_print_hello.ipynb) jupytext.write(nb, sage_print_hello.md)read负责把任意格式的笔记本载入统一的nbformat对象write再根据目标扩展名.md选择 Markdown 输出器完成序列化。这种双向读写机制与仓库中 tests/functional/simple_notebooks/test_read_simple_ipynb.py 体现的读写一致性思路一致Jupytext 保证write产出的文本能再次被read还原为等价笔记本。反向转换从 Markdown 回到 Sage 笔记本Jupytext 的转换是双向的把上面的 Markdown 文本还原成.ipynbjupytext --to ipynb sage_print_hello.md -o sage_print_hello.ipynb或import jupytext nb jupytext.read(sage_print_hello.md) jupytext.write(nb, sage_print_hello.ipynb)此时 YAML 元数据头中的kernelspecdisplay_name: SageMath 9.2、language: sage、name: sagemath会被重新注入笔记本元数据保证还原后的笔记本仍使用正确的 SageMath 内核围栏代码块sage中的代码则还原为代码单元。这正是文本笔记本 ↔ 原生笔记本无损往返的核心闭环也是 Jupytext 在 Git 协作场景中让.md文件成为.ipynb的文本替身的基础。源码级原理Markdown 格式是如何定义与映射的Markdown 格式的注册在 src/jupytext/formats.py 中markdown格式通过NotebookFormatDescription注册format_namemarkdown同时支持.md与.markdown两种扩展名分别绑定MarkdownCellReader读取与MarkdownCellExporter写出两个类对应 cell 层级的反序列化与序列化.md格式当前版本号1.3最低可读版本1.0为格式演进如 2021 年起代码单元允许超过三个反引号开头的围栏见注释预留兼容空间。当write拿到扩展名为.md的目标路径时Jupytext 会据此选择MarkdownCellExporterread读取.md文件时则按格式名与扩展名反查MarkdownCellReaderread_format_from_metadata、扩展名到格式的映射逻辑同样位于 src/jupytext/formats.py 一带。代码单元到围栏代码块的渲染在 src/jupytext/cell_to_text.py 中markdown_to_text负责对 Markdown 单元源码进行转义处理而代码单元则由对应的 cell exporter 序列化为sage print(Hello world)其中围栏的语言标签 sage 取自单元语言。对本文示例而言这个语言既来自 kernelspec.language sage也由输出扩展名 .sage 的映射兜底——见下文扩展名映射。 ### 语言与扩展名的映射表 [src/jupytext/languages.py](https://link.gitcode.com/i/6426d335af38a4927e89373251dabd97) 维护了 _SCRIPT_EXTENSIONS 表其中明确登记 python .sage: {language: sage, comment: #},这意味着 Jupytext 原生识别.sage扩展名及其语言sage注释符为#Sage 脚本的 Markdown/percent/light 格式均以此为前缀参见ipynb_to_percent、ipynb_to_hydrogen等输出目录中sage_print_hello.sage的# ---/# %%写法。该表正是jupytext --to md判断目标格式、以及jupytext --to ipynb判断脚本语言类型的数据基础。Sage 内核的特殊处理重要细节从源码可以确认一个针对 Sage 笔记本的专门处理在 src/jupytext/formats.py 的auto_ext_from_metadata中# Sage notebooks have .py as the associated extension in language_info, # so we change it to .sage in that case, see #727 if auto_ext .py and metadata.get(kernelspec, {}).get(language) sage: auto_ext .sage正如本文示例笔记本的language_info.file_extension为.py所体现的SageMath 内核继承自 IPython其language_info常被标成 Python。若不特殊处理auto扩展名推断会把 Sage 笔记本错误地当成 Python 脚本输出为.py。因此 Jupytext 在检测到kernelspec.language sage时强制把自动扩展名改写为.sage。这解释了为什么仓库ipynb_to_percent与ipynb_to_hydrogen目录下同源输出均为sage_print_hello.sage而非.py。多格式家族中的同一输入从测试集看输出差异同一输入笔记本在仓库测试输出目录中衍生出多个文本形态方便对比不同格式的差异tests/data/notebooks/outputs/ipynb_to_md/sage_print_hello.mdYAML 元数据头 sage围栏代码块本文主题tests/data/notebooks/outputs/ipynb_to_percent/sage_print_hello.sage# ---注释形式元数据头 # %%分隔的 percent 脚本tests/data/notebooks/outputs/ipynb_to_hydrogen/sage_print_hello.sage氢格式同样以# %%分隔tests/data/notebooks/outputs/ipynb_to_myst/sage_print_hello.mdMyST Markdown 变体tests/data/notebooks/outputs/ipynb_to_Rmd/sage_print_hello.RmdR Markdown 变体tests/data/notebooks/outputs/ipynb_to_script/sage_print_hello.sage纯脚本light变体。这些文件共同构成 Jupytext 的多格式回归测试集同一笔记本在不同格式间往返转换后应保持语义等价这正是 tests/round_trip 与test_sample_notebooks_are_normalized等测试要守护的核心不变量。用户在选型时可据此判断追求可读性选 Markdown/MyST追求脚本化执行选 percent/light。实战建议与适用前提元数据头是内核还原的关键请保留 Markdown 文本开头的jupyter.kernelspec段。反向转换时 Jupytext 会据此恢复内核配置若手工删除还原出的笔记本将丢失内核信息需在 Jupyter 中重新选择 SageMath 内核。execution_count与输出不会进入 Markdown轻量 Markdown 格式不记录执行计数与单元格输出因此转换常用于代码 元数据的版本控制场景需要保留输出时请改用--to ipynb的原生格式或按需配置。版本兼容.md的 Markdown 格式版本为 1.3最低可读 1.0老版本生成的 Markdown 文本仍可被当前版本读取跨大版本升级时建议先做一次往返转换验证。SageMath 的.sage自动扩展名依赖本文所述的auto_ext_from_metadata特殊分支使用auto扩展名配对如formats ipynb,sage:auto一类配置时Sage 笔记本会正确落到.sage无需手动指定扩展名。至此从最简print(Hello world)笔记本出发你已经走通了 SageMath 笔记本 → Markdown → 反向还原的完整链路并掌握了 Jupytext 在格式注册、语言映射与 Sage 内核适配上的底层设计。将同样的方法套用到你自己的 SageMath或其他语言内核笔记本上即可立即获得 Git 友好的文本化协作体验。赞分享开发工具【免费下载链接】jupytextJupyter Notebooks as Markdown Documents, Julia, Python or R scripts项目地址https://gitcode.com/gh_mirrors/ju/jupytext点击查看免费下载相关推荐Apache Flink SQL Gateway 完全指南架构原理、启动配置与 REST 查询实战Apache Flink SQL Gateway 完全指南架构原理、启动配置与 REST 查询实战 SQL Gateway 是 Apache Flink 提供开发工具Lighthouse硬编码UI字符串翻译langinfo.yml的strings字段详解Lighthouse硬编码UI字符串翻译langinfo.yml的strings字段详解 Lighthouse 是 HarbourMasters 出品的《班卓开发工具pandas v0.16.1 版本解析CategoricalIndex、sample 抽样与字符串访问器的里程碑式增强pandas v0.16.1 版本解析CategoricalIndex、sample 抽样与字符串访问器的里程碑式增强 pandas v0.16.12015开发工具上一篇Labwc集成方案如何与waybar、swaybg等工具完美协作下一篇探索未来的代码管理工具MGit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Jupytext 将 SageMath 笔记本转换为 Markdown：以 `sage_print_hello.ipynb` 为例的端到端实战
开发工具【免费下载链接】jupytextJupyter Notebooks as Markdown Documents, Julia, Python or R scripts项目地址https://gitcode.com/gh_mirrors/ju/jupytext点击查看免费下载Jupytext 的核心能力是把 Jupyter 笔记本.ipynb与纯文本格式Markdown、脚本等相互转换让笔记本可以被 Git 友好地版本管理和协作。本文以仓库测试集中一个最简 SageMath 笔记本sage_print_hello.ipynb为例完整演示并剖析 Sage 笔记本 → Markdown 的转换流程从 YAML 元数据头的生成、代码单元到围栏代码块的映射到命令行与 Python API 两种实操方式再到反向转换与源码级原理验证帮助读者在任意语言内核尤其是 SageMath上快速上手 Jupytext 的文本化工作流。转换产物一瞥输入与输出对照关联文档tests/data/notebooks/outputs/ipynb_to_md/sage_print_hello.md是转换的最终产物内容极简但完整--- jupyter: kernelspec: display_name: SageMath 9.2 language: sage name: sagemath --- sage print(Hello world)其上游输入是 [tests/data/notebooks/inputs/ipynb_sage/sage_print_hello.ipynb](https://link.gitcode.com/i/13380073bd58bf9aea2372d0cca7656e) - 笔记本只有一个 code 类型单元源代码为 print(Hello world)execution_count 为 null、无输出 - 顶层 metadata.kernelspec 声明内核为 SageMath 9.2display_name: SageMath 9.2、language: sage、name: sagemath - language_info 记录 name: python、file_extension: .py、codemirror_mode 为 ipython 3 等——这是 Sage 内核继承自 IPython 环境的典型特征也是下方源码分析中一个关键细节。 对照两张表可以发现**转换并非机械复制单元内容**而是做了三件事剥离执行计数与输出轻量 Markdown 格式只承载代码与元数据、把 kernelspec 元数据重新组织成 Jupytext 的 YAML 元数据头、把代码单元渲染成带语言标签 sage 的 Markdown 围栏代码块。 ## 把 Sage 笔记本变成 Markdown 的两种实操方式 ### 方式一命令行转换CLI 与 README 中 convert a notebook in one format to another with jupytext --to ipynb notebook.py见 [README.md](https://link.gitcode.com/i/4c8680e0fcd27acf9e879b616b6b7020)对应方向反过来即可 bash # 将 Sage 笔记本转换为 Markdown 文本笔记本 jupytext --to md tests/data/notebooks/inputs/ipynb_sage/sage_print_hello.ipynb # 若希望生成独立的指定输出文件使用 -o 指定输出路径 jupytext --to md tests/data/notebooks/inputs/ipynb_sage/sage_print_hello.ipynb -o sage_print_hello.md生成的sage_print_hello.md即与ipynb_to_md目录下的输出一致。--to md中的md对应 Jupytext 的markdown格式format_namemarkdown、extension.md见下文 formats 源码。需要注意在转换命令没有显式加-o时输出文件路径由目标扩展名推导运行时请依据实际工作目录合理组织输入输出避免覆盖同名文件。方式二Python API 调用在 Python 会话中调用同样简单import jupytext nb jupytext.read(tests/data/notebooks/inputs/ipynb_sage/sage_print_hello.ipynb) jupytext.write(nb, sage_print_hello.md)read负责把任意格式的笔记本载入统一的nbformat对象write再根据目标扩展名.md选择 Markdown 输出器完成序列化。这种双向读写机制与仓库中 tests/functional/simple_notebooks/test_read_simple_ipynb.py 体现的读写一致性思路一致Jupytext 保证write产出的文本能再次被read还原为等价笔记本。反向转换从 Markdown 回到 Sage 笔记本Jupytext 的转换是双向的把上面的 Markdown 文本还原成.ipynbjupytext --to ipynb sage_print_hello.md -o sage_print_hello.ipynb或import jupytext nb jupytext.read(sage_print_hello.md) jupytext.write(nb, sage_print_hello.ipynb)此时 YAML 元数据头中的kernelspecdisplay_name: SageMath 9.2、language: sage、name: sagemath会被重新注入笔记本元数据保证还原后的笔记本仍使用正确的 SageMath 内核围栏代码块sage中的代码则还原为代码单元。这正是文本笔记本 ↔ 原生笔记本无损往返的核心闭环也是 Jupytext 在 Git 协作场景中让.md文件成为.ipynb的文本替身的基础。源码级原理Markdown 格式是如何定义与映射的Markdown 格式的注册在 src/jupytext/formats.py 中markdown格式通过NotebookFormatDescription注册format_namemarkdown同时支持.md与.markdown两种扩展名分别绑定MarkdownCellReader读取与MarkdownCellExporter写出两个类对应 cell 层级的反序列化与序列化.md格式当前版本号1.3最低可读版本1.0为格式演进如 2021 年起代码单元允许超过三个反引号开头的围栏见注释预留兼容空间。当write拿到扩展名为.md的目标路径时Jupytext 会据此选择MarkdownCellExporterread读取.md文件时则按格式名与扩展名反查MarkdownCellReaderread_format_from_metadata、扩展名到格式的映射逻辑同样位于 src/jupytext/formats.py 一带。代码单元到围栏代码块的渲染在 src/jupytext/cell_to_text.py 中markdown_to_text负责对 Markdown 单元源码进行转义处理而代码单元则由对应的 cell exporter 序列化为sage print(Hello world)其中围栏的语言标签 sage 取自单元语言。对本文示例而言这个语言既来自 kernelspec.language sage也由输出扩展名 .sage 的映射兜底——见下文扩展名映射。 ### 语言与扩展名的映射表 [src/jupytext/languages.py](https://link.gitcode.com/i/6426d335af38a4927e89373251dabd97) 维护了 _SCRIPT_EXTENSIONS 表其中明确登记 python .sage: {language: sage, comment: #},这意味着 Jupytext 原生识别.sage扩展名及其语言sage注释符为#Sage 脚本的 Markdown/percent/light 格式均以此为前缀参见ipynb_to_percent、ipynb_to_hydrogen等输出目录中sage_print_hello.sage的# ---/# %%写法。该表正是jupytext --to md判断目标格式、以及jupytext --to ipynb判断脚本语言类型的数据基础。Sage 内核的特殊处理重要细节从源码可以确认一个针对 Sage 笔记本的专门处理在 src/jupytext/formats.py 的auto_ext_from_metadata中# Sage notebooks have .py as the associated extension in language_info, # so we change it to .sage in that case, see #727 if auto_ext .py and metadata.get(kernelspec, {}).get(language) sage: auto_ext .sage正如本文示例笔记本的language_info.file_extension为.py所体现的SageMath 内核继承自 IPython其language_info常被标成 Python。若不特殊处理auto扩展名推断会把 Sage 笔记本错误地当成 Python 脚本输出为.py。因此 Jupytext 在检测到kernelspec.language sage时强制把自动扩展名改写为.sage。这解释了为什么仓库ipynb_to_percent与ipynb_to_hydrogen目录下同源输出均为sage_print_hello.sage而非.py。多格式家族中的同一输入从测试集看输出差异同一输入笔记本在仓库测试输出目录中衍生出多个文本形态方便对比不同格式的差异tests/data/notebooks/outputs/ipynb_to_md/sage_print_hello.mdYAML 元数据头 sage围栏代码块本文主题tests/data/notebooks/outputs/ipynb_to_percent/sage_print_hello.sage# ---注释形式元数据头 # %%分隔的 percent 脚本tests/data/notebooks/outputs/ipynb_to_hydrogen/sage_print_hello.sage氢格式同样以# %%分隔tests/data/notebooks/outputs/ipynb_to_myst/sage_print_hello.mdMyST Markdown 变体tests/data/notebooks/outputs/ipynb_to_Rmd/sage_print_hello.RmdR Markdown 变体tests/data/notebooks/outputs/ipynb_to_script/sage_print_hello.sage纯脚本light变体。这些文件共同构成 Jupytext 的多格式回归测试集同一笔记本在不同格式间往返转换后应保持语义等价这正是 tests/round_trip 与test_sample_notebooks_are_normalized等测试要守护的核心不变量。用户在选型时可据此判断追求可读性选 Markdown/MyST追求脚本化执行选 percent/light。实战建议与适用前提元数据头是内核还原的关键请保留 Markdown 文本开头的jupyter.kernelspec段。反向转换时 Jupytext 会据此恢复内核配置若手工删除还原出的笔记本将丢失内核信息需在 Jupyter 中重新选择 SageMath 内核。execution_count与输出不会进入 Markdown轻量 Markdown 格式不记录执行计数与单元格输出因此转换常用于代码 元数据的版本控制场景需要保留输出时请改用--to ipynb的原生格式或按需配置。版本兼容.md的 Markdown 格式版本为 1.3最低可读 1.0老版本生成的 Markdown 文本仍可被当前版本读取跨大版本升级时建议先做一次往返转换验证。SageMath 的.sage自动扩展名依赖本文所述的auto_ext_from_metadata特殊分支使用auto扩展名配对如formats ipynb,sage:auto一类配置时Sage 笔记本会正确落到.sage无需手动指定扩展名。至此从最简print(Hello world)笔记本出发你已经走通了 SageMath 笔记本 → Markdown → 反向还原的完整链路并掌握了 Jupytext 在格式注册、语言映射与 Sage 内核适配上的底层设计。将同样的方法套用到你自己的 SageMath或其他语言内核笔记本上即可立即获得 Git 友好的文本化协作体验。赞分享开发工具【免费下载链接】jupytextJupyter Notebooks as Markdown Documents, Julia, Python or R scripts项目地址https://gitcode.com/gh_mirrors/ju/jupytext点击查看免费下载相关推荐Apache Flink SQL Gateway 完全指南架构原理、启动配置与 REST 查询实战Apache Flink SQL Gateway 完全指南架构原理、启动配置与 REST 查询实战 SQL Gateway 是 Apache Flink 提供开发工具Lighthouse硬编码UI字符串翻译langinfo.yml的strings字段详解Lighthouse硬编码UI字符串翻译langinfo.yml的strings字段详解 Lighthouse 是 HarbourMasters 出品的《班卓开发工具pandas v0.16.1 版本解析CategoricalIndex、sample 抽样与字符串访问器的里程碑式增强pandas v0.16.1 版本解析CategoricalIndex、sample 抽样与字符串访问器的里程碑式增强 pandas v0.16.12015开发工具上一篇Labwc集成方案如何与waybar、swaybg等工具完美协作下一篇探索未来的代码管理工具MGit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考