jupyter-book-example

This repository demonstrates a working implementation of Jupyter Book, hosted on GitHub Pages, with automated deployments setup via GitHub Actions.

For more context about this process, or if you would like to start from scratch to setup your own book, consult the official Jupyter Book Tutorial.

Otherwise, if you'd like to build on top of this template repository, follow the instructions below.

Setup

Repo Setup

Make a copy of this template repository by clicking "Use this template" > "Create a new repository" from the green button on the top right of the template repository homepage on GitHub.

There is also a one-time setup step to get your GitHub Actions build to pass and get your site hosted. In your GitHub repository's settings, under the "pages" settings, configure GitHub Pages, specifically choosing to deploy from "GitHub Actions" source. For more details, see the "Deploying" section below.

NOTE: the GitHub Actions build for your new repository may be failing initially, until you configure GitHub Pages. It's OK. You can always return to configure GitHub Pages when you are ready to host your site.

Local Setup

Clone your copy of the repository onto your local computer, and navigate there from the command line.

Setup a project-specific virtual environment, if you like that kind of thing (otherwise use an existing environment):

# using python 3.10 for example, but you can choose a different version if you'd like:
conda create -n jbook-env python=3.10
conda activate jbook-env

Install the Jupyter Book Package, for example via pip:

# install just the jupyter book package into your environment:
#pip install jupyter-book

# consider alternatively leveraging the requirements file:
pip install -r requirements.txt

Managing the Book

Initializing

FYI - the following command was used to create the structure for this book (where "docs" was chosen as the name of the book):

jupyter-book create docs

If you have created a copy of this repository, you won't need to repeat this initialization step.

Customizing

There are a number of opportunities to customize the book configuration via the "_config.yml" file (for example, updating the logo). The sidebar navigation can be customized via the "_toc.yml" file. See the Jupyter Book Configuration Reference for more details.

Also customize the content for your book, adding new markdown and notebook files to your book directory, as desired.

If you are including IPYNB notebooks in your book, and if these notebooks use any third-party Python packages, you must update the "requirements.txt" file to include the names of those packages.

Building

NOTE: the commands below assume your book is named "docs", however if you choose a different book name, you'll need to update the commands accordingly

Build book as LaTeX (see "docs/_build/latex"):

jupyter-book build docs/ --builder latex

Build book as PDF (see "docs/_build/latex/book.pdf"):

jupyter-book build docs/ --builder pdflatex

Build book as HTML: (see "docs/_build/html/index.html"):

jupyter-book build docs/ --builder html

Clearing the cache, as necessary:

jupyter-book clean docs/ --all

Deploying

We want to publish a GitHub Pages site using a GitHub Actions workflow. See also the Jupyter Book GitHub Pages Guide.

The "deploy-book.yml" workflow file controls the build process, and has been created for you already. If you use your own book name, customize "docs" in this file to refer to the book name you chose (see lines 15, 60, and 66).

By following the "Repo Setup" section above, you will have configured your repository to be hosted on GitHub Pages.

Commit and push to trigger an automated build of your HTML site. Visit the hosted site at your repository's GitHub Pages URL. You can find the hosted site URL from your GitHub Pages settings, once the site has been deployed! It should resemble the format https://USERNAME.github.io/REPO_NAME.