How to Create a Jupyter Book

Starting from Create your first book the following steps were taken.

Basics

After creating this repo, cloning it (assume it is called root locally), I run the following from the commandline in the folder containing root.

pip install -U jupyter-book
jupyter-book build .

The book can now be opened in a browser by opening the file _build/html/index.html. On a mac, simply run open _build/html/index.html

jupyter-book build .
open _build/html/index.html

Publish on the web

Following Publish your book online install ghp-import with pip install ghp-import and then publish the book by running

ghp-import -n -p -f _build/html

This makes the book available online at https://USERNAME.github.io/REPONAME. It also keeps the source files in the main-branch separate from the html-files in _build in the gh-pages branch.

Create a pdf

Following Build a PDF, I first run pip install pyppeteer to use with jb build . --builder pdfhtml but this produced the error pyppeteer.errors.TimeoutError: Navigation Timeout Exceeded: 30000 ms exceeded. The following did produce a pdf.

jb build . --builder pdflatex

This would need some work by hand to have a nice layout. Maybe worth the effort once a book reaches a state where a book can be considered more or less finished …

Important commands

If, for example, the table of contents in the left-hand pane behaves in a strange way, clean out _build:

jupyter-book build .                # compile the md files to html
open _build/html/index.html         # read html in browser
ghp-import -n -p -f _build/html     # publish html on github
jupyter-book clean .                # delete auxiliary files