--- interact_link: content/features/jupytext.md kernel_name: python3 has_widgets: false title: 'BETA - Using Jupytext for text-based Notebook content' prev_page: url: /features/citations.html title: 'BETA - Citations and bibliographies' next_page: url: /features/layout.html title: 'BETA - Controlling page layout' comment: "***PROGRAMMATICALLY GENERATED, DO NOT EDIT. SEE ORIGINAL FILES IN /content***" ---
✨experimental✨
It's also possible to build Jupyter Books using Jupytext, a tool for
two-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 for collaboration and "diffing" using a tool like Git. The drawbacks are that you no longer keep the outputs with your files, which means building your book with outputs requires running each file at build-time.
For example, the notebook for this page is stored in a Jupytext format. In this case, we've used a 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'})
# 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'})
There are many supported formats in Jupytext. Jupyter Book works with a subset of common ones:
.md
or .markdown
).py
with Sphinx-Gallery or %%
syntax to break cells).Rmd
)Even if you're storing your content in a text-based file, it's useful to write your content in notebooks and convert them to text format before committing them in Git. This allows you to add tags to your notebooks that propagate to your Jupytext format. This allows you to use the editing capabilities of a Jupyter interface, but the version-control benefits of a text-based file.