This page contains more advanced and complete information about the
jupyter-book repository. See the sections below.
These are empty by default, but are loaded into your HTML’s header. They can be used to style your book however you’d like. For example, you may want to apply some of the distill.pub stylesheets.
Hide cells or cell outputs in the built site
Sometimes you want to use code to generate visualizations or prepare data,
but you don’t want users to see it in your built book. To prevent code cells
from showing up in your built site, you can use the following two configuration
options in your
*To remove entire code cells from your book, use the following configuration:
hide_cell_text : "YOUR TEXT"
Any code cell with the value of
hide_cell_text (above it is
will not show up in your built book.
*To remove only the code, but retain the outputs or a cell, use the following configuration:
hide_code_text: "YOUR TEXT"
Any code cell with the value of
hide_code_text (above it is
will show the output (e.g. images, HTML, etc) but not the input code that
generated this output.
In both cases, the cells will remain in the notebooks themselves, they simply won’t show up in the site’s HTML, so links that point to a JupyterHub/ Binder/etc will still work as expected.
Retain custom YAML front-matter in your files
Jupyter book will check your files for YAML front-matter and will append any newly-generated YAML to the built files for the page. This means you can provide your own custom YAML to files (which may be useful if you’d like to modify this site’s HTML).
Be careful not to add YAML with the same key names as the auto-generated YAML, as this will create duplicated keys in your page’s front-matter.
Add buttons to direct users to a JupyterHub or BinderHub
It is often helpful to let readers quickly interact with their own version of a page in order to run the code, experiment, etc. Since many of the pages in a Jupyter book are powered by notebooks, it is possible to set up a JupyterHub/BinderHub with an environment that is needed to run your book’s content.
You can place a button at the top of each page that will direct users to a JupyterHub that you specify and load the content from that page. To enable this, use the following configuration:
You can configure this button according to the location of the JupyterHub/BinderHub that you have set up. For example,
hub_url : "https://<url-to-your-hub>" # The URL for your JupyterHub/BinderHub. # ['binder', 'jupyterhub'] Whether to build interact links for a BinderHub or a JupyterHub hub_type : "binder"
Alternatively, you can use
https://mybinder.org for your
hub_url in order to
use the free mybinder.org service.
Make your static pages interactive with Thebelab
Thebelab is a project to automatically turn
static code cells into interactive cells powered by a Binder kernel. This is triggered
Thebelab button at the top of each page that has been generated from a notebook.
To make this button appear, use the following configuration in your
use_thebelab_button : true
List of relevant files
There are a few moving parts associated with Jupyter Books, and this section tries to cover most of the relevant pieces. The following list contains some of the more important files/folders worth knowing about.
content/contains all course content in Jupyter notebook or markdown form
Auto-generated folders and files
_build/contain markdown and assets created when you run
make book. This is what Jekyll uses to serve your site.
_site/contains the HTML for the built site. It is created by Jekyll, and should only exist if you build the site locally
Repository configuration and build files
_config.ymlcontains all site configuration.
_data/toc.ymlcontains the table of contents for the book (AKA, the sidebar)
requirements.txtcontains the packages needed to run the notebooks in the Jupyter book
build-requirements.txtcontains the packages needed to build the Jupyter book
scripts/contains scripts to generate the textbook from the Jupyter notebooks. These helper scripts are all run with the
Makefileincluded with this repository.
scripts/generate_book.pywill generate the markdown for your book. After you make any changes in
contents/, you should run this script via
make bookso your site stays up-to-date.
scripts/clean.pyis used to clean out any auto-generated files
scripts/execute_all_notebooks.pywill use nbconvert to execute all notebooks in