Connecting content with JupyterHub and Binder

Because Jupyter Books are built with Jupyter Notebooks, you can connect your onlinebook with a Jupyter kernel running in the cloud. This lets readers quickly interactwith your content in a traditional coding interface using either JupyterHub or BinderHub.This page describes a few ways to accomplish this.

Creating interact buttons for BinderHub

BinderHub can be used to build the environment needed to run a repository, and providesa link that lets others interact with that repository. If your Jupyter Book is hosted onlineon 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 codedoesn't require a significant amount of CPU or RAM, you can use the free, public BinderHub runningat https://mybinder.org.

To automatically include Binder link buttons in each page of your Jupyter Book, use the followingconfiguration:

  1. # Binder link settings
  2. use_binder_button                : true  # If 'true', add a binder button for interactive links

In addition, you can configure the components of your Binder links, which control things likewhere your BinderHub exists, which repository is used to define the environment, etc. Here'san example configuration with some explanation of each field.

  1. binderhub_url                    : "https://mybinder.org"  # The URL for your BinderHub.
  2. binder_repo_base                 : "https://github.com/"  # The site on which the textbook repository is hosted
  3. binder_repo_org                  : "jupyter"  # The username or organization that owns this repository
  4. binder_repo_name                 : "jupyter-book"  # The name of the repository on the web
  5. binder_repo_branch               : "master"  # The branch on which your textbook is hosted.
  6. binderhub_interact_text          : "Interact"  # The text that interact buttons will contain.

Creating interact buttons for JupyterHub

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

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

  1. use_jupyterhub_button            : false  # If 'true', display a button that will direct users to a JupyterHub (that you provide)

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

  1. jupyterhub_url                   : ""  # The URL for your JupyterHub.

Letting users define their own JupyterHub location

✨Experimental✨

If you use interact links with your Jupyter Book, you can also allow users to updatethese links to their own JupyterHub location by using parameters specified in the URL.If an interact button is present on a page, append the following to a page's URL in orderto update where the link points:

  1. mybook.com/mypage?jupyterhub=myhuburl.com

You should see a message displayed next to the interact link that lets the user knowwhere the link now points. This can be useful if you'd like to share content but allowusers to run this content wherever they like.

This page was created by The Jupyter Book Community