Jupytext.nvim

Seamlessly open Jupyter Notebooks as there associated plain text alternatives. Powered by jupytext.

jupytext.nvim is a lua port of the original jupytext.vim with some additional features and a simpler configuration.

Installation

lazy.nvim example:

return {
  "GCBallesteros/jupytext.nvim",
  config = true,
  -- Depending on your nvim distro or config you may need to make the loading not lazy
  -- lazy=false,
}

For jupytext.nvim to run correctly you will also need to make sure that you have the jupytext CLI installed (pip install jupytext).

If jupytext is available and yet when you open a notebook you still see a wall of inscrutable JSON then it may be that jupytext.nvim wasn't available due to lazy loading. The easiest fix is to not lazy load this plugin. For example if using lazy.nvim just set lazy=false. This plugin is tiny and will be a rounding error on your startup time.

Configuration

The simplest configuration only requires you to decide what plain text representation you want jupytext to output. The default configuration is:

{
  style = "hydrogen",
  output_extension = "auto",  -- Default extension. Don't change unless you know what you are doing
  force_ft = nil,  -- Default filetype. Don't change unless you know what you are doing
  custom_language_formatting = {},
}

By default, the extension of the plain text file is automatically selected by jupytext. This can be modified by changing the extension from auto to any other file extension supported by Jupytext. This is most useful to those using Quarto or Markdown. Analogously, we can provide a default filetype that will be given to the new buffer by using force_ft. Again, this is only really useful to users of Quarto.

Important

Some combinations of style and extensions are incompatible and Jupytext will fail if you attempt them, e.g. the md extension with the quarto style. You will see this as an error from the read_ipynb function.

If you need something different pass your own configuration to require("jupytext").setup, e.g.

require("jupytext").setup({ style = "light" })

Tip

Quarto and markdown format users keep on reading!

By default we use the auto mode of jupytext. This will create a script with the correct extension for each language. However, this can be overridden in a per language basis if you want to. For this add to the configuration options a field named custom_language_formatting which contains a series of per language fields. For example, to convert python files to quarto markdown:

custom_language_formatting = {
  python = {
    extension = "qmd",
    style = "quarto",
    force_ft = "quarto", -- you can set whatever filetype you want here
  },
}

Or, for regular markdown:

custom_language_formatting = {
  python = {
    extension = "md",
    style = "markdown",
    force_ft = "markdown", -- you can set whatever filetype you want here
  },
}

Setting force_ft is important to get other plugins like otter.nvim working correctly.

Acknowledgements

This plugin is a lua port of goerz/jupytext.vim and it wouldn't have existed without it.