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 編輯器之間架起了橋樑，讓您無需離開終端機即可編寫、執行並預覽筆記本儲存格。