Launch buttons for interactivity

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 using either JupyterHub or BinderHub. This page describes a few ways to accomplish this.

In each case, you’ll need to tell Jupyter Book where your book content lives online. To do so, use this configuration in _config.yml:

# Information about where the book exists on the web
repository:
  url                       : https://github.com/yourusername/yourbookrepo  # Online location of your book
  book_path                 : 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)

Binder buttons for your pages

BinderHub can be used to build the environment needed to run a repository, and provides a link that lets others interact with that repository. If your Jupyter Book is hosted online on GitHub, you can automatically insert buttons that link to the Jupyter Notebook running in a BinderHub. When a user clicks the button, they’ll be taken to a live version of the page. If your code doesn’t require a significant amount of CPU or RAM, you can use the free, public BinderHub running at https://mybinder.org.

To automatically include Binder link buttons in each page of your Jupyter Book, use the following configuration in _config.yml:

launch_buttons:
  binderhub_url: "https://mybinder.org"  # The URL for your BinderHub (e.g., https://mybinder.org)

By adding this configuration, along with the repository url configuration above, Jupyter Book will insert Binder links to any pages that were built from notebook content.

Creating interact buttons for JupyterHub

JupyterHub lets you host an online service that gives users their own Jupyter servers with an environment that you specify for them. It allows you to give users access to resources and hardware that you provision in the cloud, and allows you to authenticate users in order to control who has access to your hardware.

Similar to Binder link buttons, you can also automatically include interact links that send your readers to a JupyterHub that is running a live, interactive version of your page. This is accomplished using the nbgitpuller server extension.

You can configure the location of the JupyterHub (which you may set up on your own using a guide such as zero to jupyterhub for kubernetes or the littlest jupyterhub) with the following configuration.

launch_buttons:
  jupyterhub_url: "your-hub-url"  # The URL for your JupyterHub. (e.g., https://datahub.berkeley.edu)

Live interactive pages with Thebelab

This page 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.

Warning

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 Thebelab. This provides you a 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. As an alternative to pressing the Thebelab button at the top of the page, you can press the symbol in the top right corner of each code cell to start the interactive mode.

To add a Thebelab button to your Jupyter Book pages, use the following configuration:

launch_buttons:
  thebelab                  : true

In addition, you can configure the Binder settings that are used to provide a kernel for Thebelab to run the code. These use the same configuration fields as the BinderHub interact buttons described above.

For an example, click the Thebelab 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 0x7f5938c5b810>
../_images/launchbuttons_2_1.png

Running cells in Thebelab when it is initialized

Sometimes you’d like to initialize the kernel that Thebelab 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 thebelab-init to any code cell will cause Thebelab to run this cell after it has received a kernel. Any subsequent Thebelab cells will have access to the same environment (e.g. any module imports made in the initialization cell).

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!