企业官网建设流程全解析

• 开发工具

本文围绕 jupytext 仓库中一份真实的 SAS 笔记本转换产物（tests/data/notebooks/outputs/ipynb_to_md/sas.md）展开，讲解 jupytext 如何把以 SAS 为内核的 Jupyter Notebook 无损转换为 Markdown 文档，并深入其源码实现（语言注册、注释约定、镜像测试）与同源多格式输出。读完本文，你将掌握 SAS 笔记本的 Markdown 表示结构、jupytext 的多格式转换机制，以及如何用 CLI 命令在自己的环境中完成 ipynb ↔ md 双向转换。

一、为什么需要把 SAS 笔记本转成 Markdown

SAS 是统计分析领域的经典语言，SAS Studio / Jupyter 内核（如sas_kernel）允许在笔记本中以proc步骤、宏（%macro）和宏变量（%let、%put）编写交互式分析。但.ipynb本质是 JSON 文件，难以在版本控制、代码评审和纯文本编辑器中阅读与 diff。jupytext 的核心思路是：让同一个笔记本拥有文本伴侣——Markdown、脚本或 R Markdown 等纯文本形式，与.ipynb双向同步。

本仓库中，输入笔记本 tests/data/notebooks/inputs/ipynb_sas/sas.ipynb 与其 Markdown 版本 tests/data/notebooks/outputs/ipynb_to_md/sas.md 是一对镜像样例，直接展示了这条转换链路。

二、SAS 笔记本的 Markdown 表示结构

转换产出的sas.md全文只有两个组成要素：Jupyter 头部（YAML front matter）与围栏代码块。

2.1 Jupyter 头部：记录内核信息

--- jupyter: kernelspec: display_name: SAS language: sas name: sas ---

这一 YAML 块对应原.ipynb中metadata.kernelspec字段（display_name: SAS、language: sas、name: sas）。它的作用是：当 Markdown 文件需要被读回为笔记本时，jupytext 依据kernelspec.language判定默认语言为sas，从而正确还原内核配置。从源码 src/jupytext/languages.py 的default_language_from_metadata_and_ext可见，jupytext 会依次参考jupytext.main_language、kernelspec.language和文件扩展名推断默认语言，其中sas与其他少数语言一样，被作为保留的原样语言名处理（第 123 行直接返回，不做小写化改写）。

2.2 Markdown 标题与 SAS 代码单元

YAML 头部之后，Markdown 标题行来自笔记本的 markdown 单元格：

# SAS Notebooks with jupytext

随后的 4 个 SAS 代码单元格，全部以```sas围栏代码块呈现，语言标识符sas正是 Jupyter 内核语言名：

proc sql; select * from sashelp.cars (obs=10) ; quit;

%let name = "Jupytext";

%put &name;

/* Note when defining macros "%macro" cannot be the first line of text in the cell */ %macro test; data temp; set sashelp.cars; name = "testx"; run; proc print data = temp (obs=10); run; %mend test; %test

这 4 个单元覆盖了 SAS 笔记本的典型用法：SQL 查询（proc sql）、宏变量定义（%let）、宏变量引用（%put &name）以及宏的定义与调用（%macro/%mend/%test）。代码块内保留了原单元格的全部源代码与注释，未做任何删改。

三、转换机制与源码实现

3.1 语言注册：.sas扩展名与块注释约定

jupytext 之所以能正确读写 SAS 脚本/文档，关键在于 src/jupytext/languages.py 中的注册表：

".sas": { "language": "sas", "comment": "/*", "comment_suffix": "*/", },

该条目同时出现在_SCRIPT_EXTENSIONS与_JUPYTER_LANGUAGES（第 28 行）集合中。comment: "/*"与comment_suffix: "*/"表示 SAS 采用块注释语法，这一约定在转换为脚本类格式（percent、hydrogen、light/script）时尤为重要——单元格分隔符与 Jupyter 头部都必须用/* ... */包裹。

usual_language_name（languages.py）会把小写sas规范化为"SAS"，用于单元格语言比较；magics.py中sas也被列入不使用%%magic 前缀的语言之列（src/jupytext/magics.py），即 SAS 单元格直接以代码起始，无需任何 magic 声明。

3.2 镜像测试：保证 ipynb → md 的确定性

本仓库用"镜像测试"约束转换的稳定性。在 tests/functional/round_trip/test_mirror.py 中：

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

该测试遍历tests/data/notebooks/inputs下所有输入笔记本（含ipynb_sas/sas.ipynb），用md格式执行转换，并将结果与tests/data/notebooks/outputs/ipynb_to_md/下的预生成镜像逐一比对，从而保证本文所讲的sas.md是当前版本转换逻辑的精确快照。同理，ipynb_to_Rmd、ipynb_to_myst等测试覆盖了同一笔记本的其他目标格式。

四、同一 SAS 笔记本的多种文本格式

仓库为sas.ipynb预生成了多种文本表示，是理解 jupytext "一处笔记本、多格式伴侣" 理念的最佳素材：

以 percent 格式为例，ipynb_to_percent/sas.sas 将 Jupyter 头部逐行包进/* ... */块注释，并用/* %% */与/* %% [markdown] */标记单元格边界，这正是_SCRIPT_EXTENSIONS[".sas"]中块注释配置的直接体现。

五、实战：在自己的环境中转换 SAS 笔记本

5.1 命令行转换

安装 jupytext 后，即可用 CLI 完成 ipynb 与 md 之间的转换：

# 安装（若使用 conda，可替换为 conda install -c conda-forge jupytext） pip install jupytext # ipynb → markdown jupytext --to md "sas.ipynb" # markdown → ipynb（读回为 SAS 内核笔记本） jupytext --to ipynb "sas.md" # 显式指定目标格式并输出到目录 jupytext --to md:percent "sas.ipynb"

--to md即对应仓库镜像测试中的"md"格式；--to md:percent表示"Markdown 但使用 percent 风格的单元格标记"。由于sas.md头部已写入kernelspec.language: sas，读回时内核信息不会丢失。

5.2 配对同步（Paired Notebooks）

若希望.ipynb与.md始终双向同步，可在 Jupyter 配置中启用配对：

# jupyter_notebook_config.py c.ContentsManager.contents_manager_class = "jupytext.TextFileContentsManager" c.ContentsManager.default_jupytext_formats = "ipynb,md" # 或 "ipynb,sas" 等

此后每次在 Jupyter 中保存笔记本，jupytext 会自动同时刷新配套的 Markdown 文件，适合纳入 Git 做版本管理与代码评审。

六、注意事项与限制

1. %macro不能是单元格首行：sas.md第 4 个代码块开头的注释明确提醒——定义宏时，%macro不能作为单元格文本的第一行。这是 SAS 内核/语法解析的既有约束，jupytext 忠实保留原单元格内容，并不改变 SAS 的书写规则；建议在宏定义前先写一行注释或空语句。

2. 格式选择与生态匹配：若目标是 Jupyter Book 等 MyST 生态，选md:myst；若面向 R 生态或 Knit 工作流，选Rmd；若希望保留折叠/调试能力且与 Hydrogen、VS Code 兼容，选 percent 或 hydrogen 脚本（.sas扩展名自动匹配 SAS 语法高亮）。

3. 转换确定性由测试保障：任何对语言注册表或转换逻辑的改动，都会经由 tests/functional/round_trip/test_mirror.py 的镜像比对校验，因此sas.md的形态在仓库当前版本中是稳定可复现的。

七、总结

以 tests/data/notebooks/outputs/ipynb_to_md/sas.md 为代表的转换产物表明：jupytext 对 SAS 笔记本的支持是一套完整的工程实践——语言注册表（src/jupytext/languages.py）定义了.sas扩展名与块注释约定，YAML 头部保留了kernelspec内核信息，围栏代码块完整承载proc步骤、宏变量与宏定义，而镜像测试则保证了转换的稳定与可回归。无论你选择 Markdown、MyST、R Markdown 还是 percent 脚本，都可以用同一份 SAS 笔记本驱动多种协作与发布工作流。

• 开发工具