kiyoon/jupynium.nvim

Selenium-automated Jupyter Notebook that is synchronised with Neovim in real-time.

Jupynium.nvim – 在 Neovim 内实时预览 Jupyter Notebook

简介 – 这是一个 Neovim 插件，让您可以编辑 Jupytext 风格的文件 (*.ju.py, *.ju.*)，并将所有变更实时反映在 Firefox 中打开的 Jupyter Notebook 上。它的运作方式是运行一个基于 Python 的小型服务器，通过 Selenium 与笔记本沟通，因此笔记本 UI 完全不受影响，无需安装任何内核扩展功能。

重要性 – 大多数时间都在终端编辑器中工作的科学家和开发者，现在可以在保持 Neovim 使用习惯的同时，获得笔记本丰富的交互式视图体验。同步是单向的 (Neovim → 浏览器)，这能保持工作流程简单，并避免与笔记本 UI 中的手动编辑产生冲突。

核心概念

组件	角色
Neovim 插件 (Lua)	检测 `.ju.` 文件，提供命令、按键映射以及可选集成 (补全、折叠)。
Jupynium 服务器 (Python)	接收来自 Neovim 的编辑事件，通过 Selenium 驱动 Firefox，并更新笔记本前端。
Selenium + geckodriver	自动化浏览器；受限于 Selenium 的限制，目前仅支持 Firefox。
Jupytext 百分比格式	磁盘上的文件格式 (`# %%` 用于代码单元格, `# %% [md]` 用于 Markdown)，由插件解析并同步。

主要功能 (详见 README)

实时预览 – 当您在 Neovim 中输入时，浏览器中的对应笔记本单元格会立即更新。
笔记本端零安装 – 无需 Jupyter 扩展或内核修改；一切皆通过前端完成。
支持任何内核 – 因为它仅驱动 UI，您可以使用 Python、R 或任何 Jupyter 支持的语言。
支持远程 – 笔记本可以在远程服务器上运行，而 Neovim 客户端保持在本地 (服务器只需能连接到浏览器)。
自动文件处理 – 可选的 .ipynb 副本自动下载、同步标签页自动关闭，以及自动滚动至活动单元格。
丰富集成 – nvim-cmp / blink.cmp 的补全来源、通过 nvim-ufo 进行折叠，以及模拟 LSP 的悬浮信息。
可自定义按键绑定与文本对象 – 默认快捷键 (<space>x 执行, <space>c 清除等) 皆可禁用并重新定义。
可扩展的 Lua API – Jupynium_execute_javascript 允许插件或用户脚本在笔记本环境中执行任意 JavaScript。

安装检查清单 (来自 README)

系统需求
- Neovim ≥ 0.8
- Firefox + 对应的 geckodriver
- Python ≥ 3.9 (或通过 uv/Conda 创建的虚拟环境)
- Jupyter Notebook ≥ 6.2 (经典界面；尚未支持 Notebook 7)
Python 端 – 安装插件的 Python 包 (例如 pip3 install --user . 或使用 uv/Conda)。
Neovim 端 – 使用您偏好的管理器 (vim-plug, packer.nvim, lazy.nvim 等) 加入插件，并执行安装 Python 包的构建步骤。
可选 UI 辅助 – rcarriga/nvim-notify 和 stevearc/dressing.nvim 可提供更美观的通知与选择对话框。
配置 – 在 init.lua 中调用 require("jupynium").setup({ … })。默认值适用于大多数用户；Conda 用户只需将 python_host 指向 Conda 执行文件即可。

快速入门工作流程

1. 打开一个名为 <name>.ju.py 的文件 (或您配置的任何模式)。
2. :JupyniumStartAndAttachToServer   → 启动 Firefox 并打开笔记本 UI。
3. :JupyniumStartSync                → 创建一个 Untitled.ipynb 标签页并开始同步。
4. 编辑文件 – 使用 `# %%` 开始代码单元格，`# %% [md]` 用于 Markdown。
5. 按下 <space>x 执行当前单元格 (或选择多个单元格)。
6. 完成后，使用 :JupyniumDownloadIpynb 保存 .ipynb 副本，或让自动下载选项为您处理。

所有变更皆由 Neovim 流向浏览器；不建议直接编辑笔记本，因为同步是单向的。

典型使用案例

数据科学脚本 – 在不离开您喜爱的终端编辑器的情况下编写与测试笔记本。
教学 / 实时编码 – 在您于 Neovim 中输入时，展示干净、实时的笔记本单元格预览。
远程笔记本 – 在远程机器 (例如大学的 JupyterHub) 运行笔记本服务器的同时，保持本地的 Neovim 会话。
多语言项目 – 因为插件仅操作 UI，您可以与 R、Julia 或任何其他 Jupyter 内核搭配使用。

README 中提到的限制

仅支持 Firefox (其他浏览器会破坏 Selenium 交互)。
尚未支持 Notebook 7 (新的 "nbclassic" UI)；您必须使用经典的 Notebook 6 界面。
同步方向仅限 Neovim → 浏览器；浏览器中的变更会被忽略。
此插件不适用于 JupyterLab。

后续步骤

关注仓库的 issues 以获取即将推出的 Notebook 7 支持。
探索 Lua API (Jupynium_execute_javascript) 以构建自定义动作，例如自动变量检查。
结合补全插件 (nvim-cmp, blink.cmp) 以在 Neovim 内获得内核端的补全功能。

总结 – Jupynium.nvim 在强大的交互式笔记本 UI 与高效的 Neovim 编辑器之间架起了桥梁，让您无需离开终端即可编写、执行并预览笔记本单元格。