Maxwell Rules - NeoVim Notebooks

NeoVim Notebooks

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

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!.

Iron.nvim

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.

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

vim-textobj-hydrogen

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.

Configuration

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.

call plug#begin('~/.vim/plugged')
  Plug 'hkupty/iron.nvim'
  Plug 'kana/vim-textobj-user'
  Plug 'kana/vim-textobj-line'
  Plug 'GCBallesteros/vim-textobj-hydrogen'
  Plug 'GCBallesteros/jupytext.vim'
call plug#end()

" Jupytext
let g:jupytext_fmt = 'py'
let g:jupytext_style = 'hydrogen'

" Send cell to IronRepl and move to next cell.
" Depends on the text object defined in vim-textobj-hydrogen
" You first need to be connected to IronRepl
nmap ]x ctrih/^# %%<CR><CR>

luafile $HOME/.config/nvim/plugins.lua

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:

local iron = require "iron.core"
iron.setup({
  config = {
    should_map_plug = false,
    scratch_repl = true,
    repl_definition = {
      python = {
        command = { "ipython" },
        format = require("iron.fts.common").bracketed_paste,
      },
    },
  },
  keymaps = {
    send_motion = "ctr",
    visual_send = "ctr",
  },
})

Thanks for reading!