kiyoon/jupynium.nvim

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

Jupynium.nvim – Neovim 내에서 Jupyter Notebook 라이브 미리보기

소개 – Jupytext 스타일 파일(*.ju.py, *.ju.*)을 편집하고 모든 변경 사항을 Firefox에서 실행 중인 Jupyter Notebook에 즉시 반영하는 Neovim 플러그인입니다. Python 기반의 소형 서버가 Selenium을 통해 노트북과 통신하므로 노트북 UI를 직접 수정할 필요가 없으며, 커널 확장 기능도 필요하지 않습니다.

중요성 – 터미널 에디터에서 대부분의 시간을 보내는 데이터 과학자와 개발자는 이제 Neovim의 환경을 유지하면서도 노트북의 풍부한 대화형 뷰를 활용할 수 있습니다. 동기화는 단방향(Neovim → 브라우저)으로 이루어지므로 워크플로우가 단순하게 유지되며 노트북 UI에서의 수동 편집과 충돌하지 않습니다.

핵심 개념

구성 요소	역할
Neovim 플러그인 (Lua)	`.ju.` 파일을 감지하고 명령어, 키맵, 선택적 통합(보완, 폴딩)을 제공합니다.
Jupynium 서버 (Python)	Neovim에서 편집 이벤트를 수신하여 Selenium을 통해 Firefox를 구동하고 노트북 프론트엔드를 업데이트합니다.
Selenium + geckodriver	브라우저를 자동화합니다. Selenium의 제한으로 인해 Firefox만 지원됩니다.
Jupytext 퍼센트 형식	플러그인이 파싱하고 동기화하는 디스크상의 파일 형식(`# %%`은 코드 셀, `# %% [md]`는 마크다운).

주요 기능 (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]`로 마크다운을 시작합니다.
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에서 작동하지 않습니다.

향후 계획

Notebook 7 지원을 위해 리포지토리의 이슈를 확인하세요.
Lua API(Jupynium_execute_javascript)를 탐색하여 자동 변수 검사와 같은 사용자 정의 작업을 구축하세요.
보완 플러그인(nvim-cmp, blink.cmp)과 결합하여 Neovim 내에서 커널 측 보완 기능을 활용하세요.

결론 – Jupynium.nvim은 강력한 대화형 노트북 UI와 효율적인 Neovim 에디터 사이의 간극을 메워주어, 터미널을 떠나지 않고도 노트북 셀을 작성, 실행 및 미리 볼 수 있게 해줍니다.