企业官网建设流程全解析

• 开发工具

本篇指南以仓库demo/get_started.md这份“上手演示笔记本”为核心，讲解 Jupytext 最常用的一条工作流：安装并激活插件后，通过 JupyterLab 命令面板将普通.ipynb笔记本**配对（Pair）**为 MyST / Markdown 文本笔记本，实现一次保存同时产出.ipynb与.md两份文件。你会了解配对命令背后的元数据机制、底层格式解析与同步逻辑，并掌握如何用demo/目录中的多格式示例笔记本做进一步实验，为后续把文本笔记本纳入 Git 版本控制、IDE 协作打好基础。

前置准备：安装 Jupytext 并激活 JupyterLab 插件

在本地跑通本指南前，需要先在你的 Python 环境中安装 Jupytext（该环境必须同时用于 Jupyter），然后重启 JupyterLab 服务。官方推荐两种安装方式：

pip install jupytext

或通过 conda：

conda install jupytext -c conda-forge

安装并重启后，Jupytext 在 JupyterLab 中的“激活”体现在两类变化上：

• .py、.md等文本文件被注册为notebook 类型，在文件列表中显示笔记本图标，右键即可“以笔记本方式打开”；
• 命令面板与主菜单中出现 Jupytext 专属命令，用于创建文本笔记本、配对与取消配对。

这一行为在源码中可以直接印证：JupyterLab 扩展在 registry.ts 中调用docRegistry.addFileType把.md（markdown）、.myst、.Rmd、.qmd以及各内核语言的脚本扩展注册为contentType: 'notebook'，并默认交给 Notebook 文档工厂打开；扩展入口 index.ts 声明为autoStart: true，随 JupyterLab 启动自动加载。

如果你使用的是 Binder（参考 binder/postBuild），构建脚本已预先执行了pip install jupytext及扩展配置，进入 Binder 环境即可直接体验，无需重复安装。

通过命令面板将笔记本配对为 MyST Markdown

demo/get_started.md对应的演示笔记本是一份“全新”的.ipynb——它没有附加任何特殊的 Jupytext 元数据。要让 Jupytext 在保存时自动输出多种格式，只需三步：

1. 在 JupyterLab 顶部的View菜单中点击Activate Command Palette（激活命令面板）；
2. 在面板中输入Jupytext，会看到一组命令，每条命令对应一种自动保存的文本格式；
3. 选择Pair notebook with MyST Markdown。

完成之后保存这份.ipynb：Jupytext 除了保存.ipynb本身，还会在同目录自动生成一份get_started.md，两者构成“配对笔记本”。

从源码看，这些配对命令并非硬编码写死，而是由扩展在启动时根据 tokens.ts 中定义的JUPYTEXT_PAIR_COMMANDS_FILETYPE_DATA批量注册的，其中就包含md:myst（"Pair Notebook with MyST Markdown"）、md、Rmd、qmd、auto:percent、auto:light等条目；index.ts 为每个条目生成jupytext:pair-nb-with-<format>命令，并同时挂入命令面板（category: 'Jupytext'）与 JupyterLab 主菜单下的Jupytext子菜单。

如上图所示，命令面板中不仅能看到 “Pair Notebook with MyST Markdown”，还并列着 light Script、percent Script、Markdown、R Markdown、Quarto 等多种配对目标，以及Custom pairing和Unpair Notebook两个特殊条目——它们对应的正是“自定义配对”与“解除配对”。

配对背后的机制：一切由 jupytext 元数据驱动

“Jupytext 怎么知道该把笔记本保存成什么格式？”答案是：配对信息以 YAML 形式写在笔记本的jupyter级元数据中。demo/get_started.md文件开头就是配对完成后写入.ipynb元数据（并同步渲染到文本文件头部）的样例：

jupyter: jupytext: formats: ipynb,md text_representation: extension: .md format_name: markdown format_version: '1.1' jupytext_version: 1.1.6 kernelspec: display_name: Python 3 language: python name: python3

关键字段含义如下：

在笔记本中直接观察元数据

原文档提供了一段代码，让你在笔记本里实时查看配对所写入的元数据：

import nbformat as nbf from IPython.display import JSON notebook = nbf.read('./get_started.ipynb', nbf.NO_CONVERT) JSON(notebook['metadata'])

每当你从命令面板选择不同的配对格式并保存笔记本，metadata中的jupytext.formats就会随之变化——这正说明配对状态完全由这份元数据承载，文件本身只是它的投影。

源码级验证：元数据如何被读写与校验

• 写入端（JupyterLab 扩展）：commands.ts 中的executePairCommand负责切换配对：读取当前jupytext元数据 → 增删formats中的条目（保证同一扩展名只出现一次、当前文件扩展名不可被解除）→ 通过setMetadata('jupytext', ...)写回模型；若formats为空则删除整个jupytext元数据段。同一个文件还实现了 “Include Metadata” 命令（commands.ts），通过notebook_metadata_filter: '-all'开关是否在文本文件中写入 YAML 头。
• 解析端（Python 核心库）：formats.py 的long_form_one_format负责把ipynb,md这样的紧凑字符串解析为结构化字典（{'extension': ...}等），format_name_for_ext 则从元数据的text_representation或formats中反推出该文件应当使用的格式名。当格式串中写auto时，会依据language_info/kernelspec推断脚本扩展名（auto_ext_from_metadata，见 formats.py）。
• 版本校验：check_file_version（formats.py）会核对text_representation.format_version与当前安装版本支持的读取范围（如 markdown 格式支持读取 1.0–1.3），不匹配时抛出带明确升级建议的JupytextFormatError。

保存与读取时发生了什么：配对文件的同步逻辑

配对意味着同一笔记本存在多个文件副本，因此“保存时写哪里、读取时以谁为准”必须有一套明确规则。核心实现位于 pairs.py 的latest_inputs_and_outputs：它会遍历所有配对路径，比较各文件的时间戳——

• 对每个配对格式，.ipynb文件被视为输出的唯一载体（保存笔记本运行结果）；
• 其余文本文件（.md、.py等）被视为输入来源；
• 读取时选择时间戳最新的输入文件，并以.ipynb中的输出做合并，因此你编辑.md后回到 Jupyter，输入会更新而输出仍保留；
• 写入时则同时刷新所有配对格式的文件。

这也解释了原文档“保存.ipynb会顺带生成/更新.md”的现象，以及常见工作流“在 IDE 里改.py/.md，回到 Jupyter 中执行 Reload Notebook from Disk 即可拿到最新编辑”的原理。

进一步实验：demo 目录里的多格式对比

原文档最后提示我们打开仓库demo/目录中的World population.ipynb。这份示例笔记本默认配置了多格式配对，保存一次即可对比各文本格式的观感差异。与其同目录的姊妹文件给出了真实样例：

• World population.md—— 普通 Markdown 格式（其 YAML 头写明formats: ipynb,.pct.py:percent,.lgt.py:light,.spx.py:sphinx,md,Rmd,.pandoc.md:pandoc，见 World population.md）
• World population.myst.md—— MyST Markdown
• World population.pandoc.md—— Pandoc Markdown
• World population.Rmd—— R Markdown
• World population.pct.py—— percent 脚本格式
• World population.lgt.py—— light 脚本格式
• World population.spx.py—— Sphinx-gallery 脚本格式

不同格式各有适用场景：代码居多的笔记本适合percent（# %%分隔单元格）；以文档为主的笔记本适合 Markdown 系格式（MyST 与 Jupyter Book 生态互操作良好，Quarto/Pandoc 各有侧重）。百分号格式的写法可参考 demo/vscode/notebook.py：YAML 头声明formats: ipynb,py:percent，正文用# %%划分代码单元格、# %% [markdown]划分 Markdown 单元格。

此外，这些文本文件在 JupyterLab 中都被当作笔记本展示（文件类型注册见上文 registry.ts），因此可以直接右键打开运行，或直接“新建文本笔记本”后从命令面板的 Jupytext 分类中选择格式起步。

命令行入口与后续进阶

配对功能同样可以从命令行触发，适合脚本化与批量处理（命令来源：README.md）：

# 将 notebook.ipynb 与 percent 格式的 .py 配对 jupytext --set-formats ipynb,py:percent notebook.ipynb # 同步配对文件（输入取最近更新的配对文件） jupytext --sync notebook.py # 格式转换（-o 指定输出文件） jupytext --to ipynb notebook.py # 管道输出到格式化/检查工具 jupytext --pipe black notebook.ipynb

如果希望整个目录下的所有笔记本默认配对，可以在笔记本目录根放一份配置文件（如jupytext.toml）：

formats = "ipynb,py:percent"

配对文本笔记本之后，就可以把它当作普通文本文件纳入 Git 版本控制、在 IDE 中编辑重构，并与协作者进行干净可读的 diff 协作；相关完整文档位于本仓库 website/src/content/docs 下的 formats、getting-started、integrations、reference 等章节，可作为继续深入的入口。

小结：从demo/get_started.md出发，你已走通了 Jupytext 的核心闭环——命令面板一键配对、jupytext.formats元数据驱动、保存时多格式同步、读取时最新输入与.ipynb输出合并。接下来不妨按原文档建议，打开demo/World population.ipynb尝试不同格式的输出，再结合命令行与配置文件，把 Jupytext 接入自己的版本控制与 IDE 工作流。

• 开发工具