NeoVim Notebooks

This setup has been largely superseeded by my Notebook Navigator plugin. It makes it easier to interact with code cells directly in nvim and send them to an REPL. Check it out and leave a ⭐!

I have reached Vim nirvana with my latest setup. I can finally bring all the advantages of working within Jupyter to my favorite text editor. You get the code cells and interactive development with a fine-tuned editor and plain text files which can be put through linters and code formatters. Lo and behold:

As easy to navigate and execute as the Jupyter interface but with a real editor behind. I can't ask for more.

This setup is powered by the following plugins:

Of course, I use a bunch of other plugins for linting, autocompletion, code navigation... If you are interested on those you can find my init.vim here.


Jupytext logo.

Manipulating raw ipynb files is difficult and unergonomic. Tools such as notedown and jupytext make it possible to transform ipynb files to and from a plain text representation. To automate the process I use the jupytext.vim plugin. It will open the notebook and load it into the buffer as a python script. On save, it will do the roundtrip back to an ipynb for you. Very handy!.

I actually use my own fork of jupytext.vim because we need to be able to specify the output format. As soon as the pull request gets merged I'll get rid of this comment. In the meantime if you want to reproduce the setup you'll have to use GCBallesteros/jupytext.vim.


Connecting nvim with IPython couldn't be easier than using iron.nvim. It also supports many other REPLs so no matter what your language of choice it will have you covered.

Screenshot of iron repl in action.

You can either send text to the REPL via a motion/text object or through a visual selection.


The final ingredient was to have (n)vim understand code cells. I couldn't find any off-the-shelf solution but developing my own plugin wasn't too hard by building atop the excellent vim-textobj-user. The result is vim-textobj-hydrogen. It introduces two text objects, ih and ah, that correspond to cells defined in the hydrogen format. I also included two motions, ]h and [h, to quickly move across cells.


Below is all you will need to add to your nvim configuration. The only part that may require some explanation is the mapping for ]x. We start by using the IronRepl defaul map to send a motion into the REPL, i.e. ctr. Then we follow that with the text object defined in vim-textobj-hydrogen, ih and finally we run a search to reach the beginning of the next cell, /^# %%. The double <CR> turns off the highlighting that was started by the search.

Edit: To set ipython as the default REPL for python you will need to create a file plugins.lua in the same folder where init.vim is with the following contents:

Thanks for reading!