Custom notebook formats and Jupytext#
You can designate additional file types to be converted to notebooks and then executed/parsed in the same manner as regular notebooks.
Tip
This page itself is written as an RMarkdown notebook!
sphinx:
config:
nb_custom_formats:
.mysuffix: mylibrary.converter_function
The string should be a Python function that will be loaded by
import mylibrary.converter_function
The function should take a file’s contents (as a
str
) and return an nbformat.NotebookNode
If the function takes additional keyword arguments, then you can specify these as a dictionary in a second argument. For example this is what the default conversion would look like:
sphinx:
config:
nb_custom_formats:
.ipynb:
- nbformat.reads
- as_version: 4
Important
By default, Markdown cells in the notebook will be parsed using the same MyST parser configuration as for other Markdown files.
But, if this is incompatible with your file format, then you can specify for the Markdown to be parsed as strictly CommonMark, using a third argument:
sphinx:
config:
nb_custom_formats:
.ipynb:
- nbformat.reads
- as_version: 4
- true
Finally, for text-based formats, MyST-NB also searches for an optional source_map
key in the output notebook’s metadata.
This key should be a list mapping each cell to the starting line number in the original source file, for example for a notebook with three cells:
{
"metadata": {
"source_map": [10, 21, 53]
}
}
This mapping allows for “true” error reporting, as described in Warning suppression.
Using Jupytext#
Jupytext is an excellent Python tool for two-way conversion
between Jupyter Notebook .ipynb
files and
a variety of text-based files.
Jupyter Book natively supports the Jupytext file format: notebooks with MyST Markdown.
You can also add other formats like RMarkdown or Python files. To do so, first ensure Jupytext is installed:
$ pip install jupytext
Then configure Jupyter book like so:
sphinx:
config:
nb_custom_formats:
.Rmd:
- jupytext.reads
- fmt: Rmd
Warning
Note that some execution features (such as in-line code execution in RMarkdown) are not available in Jupyter Book.
Now you can use RMarkdown blocks:
```{python echo=TRUE}
print("Hallo I'm an RMarkdown block!")
```
print("Hallo I'm an RMarkdown block!")
Hallo I'm an RMarkdown block!
Convert a Jupytext file into a MyST notebook#
Alternatively, if you’d like to convert your pre-existing Jupytext files into the MyST notebook format, to use directly in your book, install Jupytext and then run the following command:
jupytext --to myst path/to/yourfile
Note that you may also pass a wildcard that will be used to convert multiple files. For example:
jupytext --to myst ./*.py
See the Jupytext CLI documentation for more information.