什么是 Jupytext？

在使用 Jupyter Lab 的时候，原生使用的文件后缀为 .ipynb，这个文件不是简单的文本文件，会混杂很多 Jupyter Lab 的输出内容和控制文本，该文本对于 Git 来说非常不友好。因此，催生了 Jupytext 这个专为 Jupyter Lab 支持纯文本文件的第三方插件，综合来说，使用该插件有以下好处：

  1. 使用 markdown 纯文件来管理 ipynb 的内容，文本内容与结果内容相分离，方便 Git 提交与多人协作，或者直接把 markdown 文件提交到支持该文件格式的托管网站发布。
  2. 可以让 ipynb 与 markdown 成对使用（pair），在两种格式之间相互转换，并且该转换为编辑保存时的实时转换。
  3. 可以使用你最喜欢的编辑器来编辑 markdown 文件。
  4. Jupyter Lab 作为非常容易部署的工具，可以作为自已的云端 Markdown 编辑器，还自带 Git 提交、对比等功能，作为云端记事本非常方便。基于到还可以支持大名鼎鼎的 RMarkdown 文件格式。但是注意，如果使用了其它文件格式扩充，在 Jupyter Lab 里可能不支持一些可执行代码的功能。

几个容易混淆的概念

  • Jupyter Notebook 或是 Jupyter Lab：一个 Python 的集成开发与可视化编程环境，边写文档边写代码边看结果，这个对应的文件格式后缀是 ipynb。
  • Jupyter Book：一个基于 Jupyter 的书籍排版软件，可用纯粹的 markdown 文件或是 ipynb 文件来生成书籍，背后的文本生成引擎使用的是 Sphinx。
  • Quarto：作为等同于 Jupyter Book，但是背后的文本生成引擎是 pandoc；并且除了可以用来作书籍排版以外，还可以用来建网站，也可以用来做与 Jupyter Lab 类似的可视化开发环境。

三者作用有重叠有交叉，有一些功能在 Jupyter Book 支持但是在 Jupyter Lab 里可能支持不好，比如显示图片及交叉索引图片等。事实上，你可以在 Jupyter Notebook 或是 Jupyter Lab 里使用 Quarto 或是 Jupyter Book 的交叉引用或是其它的规则。也就是说，你可以用 Jupyter 来作为可视化编程环境来验证你的想法，最终可以选择使用 Jupyter Book 或是 Quarto 来编译成书。

Jupytext 的问题

但是使用 Jupytext 也可能会引发莫名其妙的问题，比如在我的环境里，就碰到一个很怪异的问题：在 Jupyter Lab 里，以 Jupyter notebook 的格式打开文件编辑并运行代码，生成的结果可正常显示，但当我用 Jupyter book 来编译成书的时候，生成的结果却无法显示在 html 或是 pdf 里。

我推测在 Jupyter notebook 是不是也需要对 Jupytext 做一些特殊的设置，不过没有再深究下去。

在目前看来，我觉得使用 Jupytext 来在 Jupyter Lab 里使用文本文件来主力编辑的理由不太充分，还是应该回来 Jupyter notebook 格式，理由如下：

  1. 现在的 Jupyter Lab 里集成 Git，已经能非常好地对 Jupyter Notebook 格式进行 diff，使用方便，无需再依赖纯文本文件。

  2. 即使需要多人协作，以及为了手动提交 Git 方便，完全可以在提交内容之前，使用 Jupytext 把 Jupyter notebook 文件转为 markdown 之类的纯文件格式。

小结

所以，推荐在 Jupyter Lab 里使用 ipynb 的格式来编辑，如有特殊需要，可以转为 markdown 文件来提交到 Git 方便与他人协同。

如果只是自已使用，完全没有必要通过 Jupytext 来在 Jupyter Lab 里对 markdown 编辑来写作，徒增我今天碰到的兼容性问题。

如果还需要使用 Jupyter Book 之类的工具，更加建议直接使用 ipynb 这种原生的格式来进行写作，避免额外的问题。

软件工具也像汽车一样，原装的配件才是用着最方便的。