Jupytext with Jupyter Book

✨experimental✨

It's also possible to build Jupyter Books using Jupytext, a tool fortwo-way conversion between Jupyter Notebooks an text-based versions of a Jupyter Notebook (e.g., .md or .py).

Using Jupytext allows you to store your Jupyter Notebooks as text files, which makes them much better forcollaboration and "diffing" using a tool like Git. The drawbacks are that you no longer keep the outputs withyour files, which means building your book with outputs requires running each file at build-time.

This notebook is stored in Jupytext format!

For example, the notebook for this page is stored in a Jupytext format. In this case, we've useda markdown file. You can find the original (text-based) format here.

Below we'll show some Python code, which Jupyter Book can execute at build time.

# Import some data
import numpy as np
import matplotlib.pyplot as plt
plt.ion()

# We'll make a simple plot!
data = np.random.randn(2, 100)
 
fig, ax = plt.subplots()
ax.scatter(*data, c=data[0], s=500)
ax.text(0, 0, "Jupytext is great!", fontdict={'size': 40, 'horizontalalignment': 'center'})

Text(0, 0, 'Jupytext is great!')

Jupytext works with cell tags

You can still use cell tags in your Jupytext files by using the format that Jupytext expects.For example, the Python code below will have its code cell hidden:

# We'll make a simple plot!
data = np.random.randn(2, 100)
 
fig, ax = plt.subplots()
ax.scatter(*data, c=data[1], s=500, cmap='coolwarm')
ax.text(0, 0, "Jupytext is great!", fontdict={'size': 40, 'horizontalalignment': 'center'})

Text(0, 0, 'Jupytext is great!')

Supported Jupytext formats

There are many supported formats in Jupytext. JupyterBook works with a subset of common ones:

• Markdown files (.md or .markdown)
• Python files meant for Jupytext (.py with Sphinx-Gallery or %% syntax to break cells)
• RMarkdown files (.Rmd)

A recommended workflow with Jupytext and notebooks

Even if you're storing your content in a text-based file, it's useful to write your content in notebooksand convert them to text format before committing them in Git. This allows you to add tags to your notebooksthat propagate to your Jupytext format. This allows you to use the editing capabilities of a Jupyter interface, butthe version-control benefits of a text-based file.

This page was created by The Jupyter Book Community