{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Connecting content with JupyterHub and Binder\n",
    "\n",
    "Because Jupyter Books are built with Jupyter Notebooks, you can connect your online\n",
    "book with a Jupyter kernel running in the cloud. This lets readers quickly interact\n",
    "with your content in a traditional coding interface using either JupyterHub or BinderHub.\n",
    "This page describes a few ways to accomplish this.\n",
    "\n",
    "## Creating interact buttons for BinderHub\n",
    "\n",
    "BinderHub can be used to build the environment needed to run a repository, and provides\n",
    "a link that lets others interact with that repository. If your Jupyter Book is hosted online\n",
    "on GitHub, you can automatically insert buttons that link to the Jupyter Notebook running in a BinderHub.\n",
    "When a user clicks the button, they'll be taken to a live version of the page. If your code\n",
    "doesn't require a significant amount of CPU or RAM, you can use the free, public BinderHub running\n",
    "at https://mybinder.org.\n",
    "\n",
    "To automatically include Binder link buttons in each page of your Jupyter Book, use the following\n",
    "configuration:\n",
    "\n",
    "```yaml\n",
    "# Binder link settings\n",
    "use_binder_button                : true  # If 'true', add a binder button for interactive links\n",
    "```\n",
    "\n",
    "In addition, you can configure the components of your Binder links, which control things like\n",
    "where your BinderHub exists, which repository is used to define the environment, etc. Here's\n",
    "an example configuration with some explanation of each field.\n",
    "\n",
    "```yaml\n",
    "binderhub_url                    : \"https://mybinder.org\"  # The URL for your BinderHub.\n",
    "binder_repo_base                 : \"https://github.com/\"  # The site on which the textbook repository is hosted\n",
    "binder_repo_org                  : \"jupyter\"  # The username or organization that owns this repository\n",
    "binder_repo_name                 : \"jupyter-book\"  # The name of the repository on the web\n",
    "binder_repo_branch               : \"master\"  # The branch on which your textbook is hosted.\n",
    "binderhub_interact_text          : \"Interact\"  # The text that interact buttons will contain.\n",
    "```\n",
    "\n",
    "## Creating interact buttons for JupyterHub\n",
    "\n",
    "JupyterHub lets you host an online service that gives users their own Jupyter servers\n",
    "with an environment that you specify for them. It allows you to give users access to\n",
    "resources and hardware that you provision in the cloud, and allows you to authenticate users\n",
    "in order to control who has access to your hardware.\n",
    "\n",
    "Similar to Binder link buttons, you can also automatically include interact links that send\n",
    "your readers to a JupyterHub that is running a live, interactive version of your page. This\n",
    "is accomplished using the [nbgitpuller](https://github.com/jupyterhub/nbgitpuller) server\n",
    "extension.\n",
    "\n",
    "```yaml\n",
    "use_jupyterhub_button            : false  # If 'true', display a button that will direct users to a JupyterHub (that you provide)\n",
    "```\n",
    "\n",
    "You can configure the location of the JupyterHub (which you may set up on your own using a guide\n",
    "such as [zero to jupyterhub for kubernetes](https://z2jh.jupyter.org) or [the littlest jupyterhub](https://tljh.jupyter.org)) with the following configuration.\n",
    "\n",
    "```yaml\n",
    "jupyterhub_url                   : \"\"  # The URL for your JupyterHub.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Letting users define their own JupyterHub location\n",
    "\n",
    "✨**Experimental**✨\n",
    "\n",
    "If you use interact links with your Jupyter Book, you can also allow users to update\n",
    "these links to their own JupyterHub location by using parameters specified in the URL.\n",
    "If an interact button is present on a page, append the following to a page's URL in order\n",
    "to update where the link points:\n",
    "\n",
    "```\n",
    "mybook.com/mypage?jupyterhub=myhuburl.com\n",
    "```\n",
    "\n",
    "You should see a message displayed next to the interact link that lets the user know\n",
    "where the link now points. This can be useful if you'd like to share content but allow\n",
    "users to run this content wherever they like."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}