The Jupyter Books Guide

This repository / website is a guide for hosting your own book using Jupyter Notebooks and Jekyll. All course content is written in markdown and Jupyter Notebooks, and a set of helper scripts converts these notebooks into Jekyll-based markdown fit for hosting on the web. This short guide will help you through the process should you want to do this for your own book.

The structure underneath Jupyter Books

This page gives a general idea for what we mean by a “Jupyter Book”. Jupyter Books are essentially these two things:

  1. A collection of notebooks and markdown files. These are in content/. When you run scripts/generate_book.py, they’ll be converted to .md files (or just copied if they’re already .md files) and placed in /_build.
  2. A Table of Contents file (_data/toc.yml). This is the Table of Contents, which will be used to create the sidebar for your site. Links in this file are relative to the /content/ folder. See the TOC for this book for a couple of examples.
  3. A Jekyll configuration file that defines information about your book, such as its title or the URL of a JupyterHub you want interact links to point to. This is also how you turn on / off many features of your Jupyter Book.

To build your own Jupyter Book

To build your own Jupyter Book, you’ll follow a process similar to this (we’ll go into each step in more detail in this guide):

  • Get yourself a copy of the jupyter-book repository. Here’s the repo URL on GitHub.
  • Put your Jupyter Notebooks / markdown files in /content/
  • Edit the _data/toc.yml file for your Table of Contents. This defines the structure of your book. The location of URLs should be relative to the /content/ folder.
  • Navigate to the repo root, then run make book to convert your Jupyter Notebooks into Jekyll-ready markdown. It will be placed in /_build.
  • Push these changes to a GitHub repo you control and tell GitHub you want to build a website from your repository.
  • That’s it!

See the rest of this guide in the links to the left for detailed instructions on this process. The next section covers Setting up your environment.

For a more complete description of the relevant files for the template repository, see the Advanced topics section.