This page was generated from doc/custom-formats.ipynb. Interactive online version:

Custom Notebook Formats

By default, Jupyter notebooks are stored in files with the suffix .ipynb, which use the JSON format for storage.

However, there are libraries available which allow storing notebooks in different formats, using different file suffixes.

To use a custom format in nbsphinx, you can specify the nbsphinx_custom_formats option in your conf.py file. You have to provide the file extension and a conversion function that takes the contents of a file (as a string) and returns a Jupyter notebook object.

nbsphinx_custom_formats = {
    '.mysuffix': 'mylibrary.converter_function',
}

The converter function can be given as a string or as a function object.

One example for such library is jupytext, which allows storing the contents of Jupyter notebooks in Markdown and R-Markdown, as well as plain Julia, Python and R files.

Since its conversion function takes more than a single string argument, just using the function name 'jupytext.reads' will not work. We have to create a function object, and one way to do that is using a lambda function like this:

import jupytext

nbsphinx_custom_formats = {
    '.Rmd': lambda s: jupytext.reads(s, '.Rmd'),
}

You can of course use multiple formats by specifying multiple conversion functions.