Connect with interactive environments¶
Because Jupyter Books are built with Jupyter notebooks, you can allow users to launch live Jupyter sessions in the cloud directly from your book. This lets readers quickly interact with your content in a traditional coding interface. There now exist numerous online notebook services - a good comparison is provided in this article - and the following sections describes the available integrations provided by Jupyter Book.
In each case, you’ll need to tell Jupyter Book where your book content lives online.
To do so, use this configuration in
# Information about where the book exists on the web repository: url : https://github.com/yourusername/yourbookrepo # Online location of your book path_to_book : path/to/book # Optional path to your book, relative to the repository root branch : master # Which branch of the repository should be used when creating links (optional)
A quick description of each option is below:
A GitHub repository that includes your source files used to build the Jupyter Book.
These files can either be in the root of the repository, or in a sub-folder (in which case you should use
A path, relative to your repository’s root, to your book’s source files.
Use this if your book is in a sub-folder of your repository (e.g.
The branch where your book’s source files are stored (not your book’s build files, which generally exist in
Control the notebook interface that opens¶
Binder and JupyterHub sessions can be opened using either the “classic” Jupyter Notebook or the new JupyterLab interface backend (see jupyter.org for more details). This is configured using:
launch_buttons: notebook_interface: "jupyterlab" # or "classic"
One thing to take into account when choosing the interface is that notebooks written in the MyST Markdown text-based format will not be opened as notebooks out-of-the-box.
If you wish for these files to be opened as notebooks then firstly you must ensure that
jupytext>=0.16 is installed in the Binder/JupyterHub environment for your book (no support for this feature exists in Google Colab).
You then have two options:
Use the “classic” interface, which will then immediately open these files as notebooks.
The “jupyterlab” interface (at the time of writing) has not yet implemented this behaviour, and so you will need to instruct readers to right-click the Markdown file and click “Open in notebook editor”.
Live interactive pages with Thebe¶
This section describes how to bring interactivity to your book. This lets users run code and see outputs without leaving the page. Interactivity is provided by a kernel running on the public MyBinder service.
This is an experimental feature, and may change in the future or work unexpectedly.
To make your content interactive without requiring readers to leave the current page, you can use a project called Thebe. This provides you with a Live Code button that, when clicked, will convert each code cell into an interactive cell that can be edited. It also adds a “run” button to each cell, and connects to a Binder kernel running in the cloud.
To add a Thebe button to your Jupyter Book pages, use the following configuration:
launch_buttons: thebe : true
In addition, you can configure the Binder settings that are used to provide a kernel for Thebe to run the code. These use the same configuration fields as the BinderHub interact buttons described above.
For an example, click the Thebe button above on this page, and run the code below.
import numpy as np import matplotlib.pyplot as plt plt.ion() x = np.arange(500) y = np.random.randn(500) fig, ax = plt.subplots() ax.scatter(x, y, c=y, s=x)
<matplotlib.collections.PathCollection at 0x7f24a3a68850>
Running cells in Thebe when it is initialized¶
Sometimes you’d like to initialize the kernel that Thebe uses by running some code ahead of time. This might be code that you then hide from the user in order to narrow the focus of what they interact with. This is possible by using Jupyter Notebook tags.
Adding the tag
thebe-init to any code cell will cause Thebe to
run this cell after it has received a kernel. Any subsequent Thebe cells
will have access to the same environment (e.g. any module imports made in the
You can then pair this with something like
hide-input in order to run
initialization code that your user doesn’t immediately see. For example,
below we’ll initialize a variable in a hidden cell, and then tell another
cell to print the output of that variable.
my_hidden_variable = 'wow, it worked!'
# The variable for this is defined in the cell above! print(my_hidden_variable)
wow, it worked!