In this beginner-friendly tutorial, we will learn how to publish online books using Jupyter Book and GitHub Pages. In this tutorial, everything will be discussed in detail. Although you don’t need any pre-requisites as such to follow this tutorial, it is better if you have previous knowledge of markdown syntax and Git commands.
At the end of this tutorial, you will be ready to publish your online book hosted by GitHub. One of the significant benefits of using Jupyter Book and GitHub Pages is that you can easily update the book’s contents at any time. You can also make use of the version control feature of Git. A demo book created using the method discussed in this tutorial is available at this link.
Here, I am assuming that Python 3, Jupyter Notebook, and Git are installed on your system. This tutorial consists of three major parts. In the beginning, we will see how to create the contents of the book. Then we will learn how to create a book from these contents using Jupyter Book. In the end, we will discuss the (free) hosting of this book using GitHub Pages.
Creating contents of the book
At first, we need to create the contents of the book. The book chapters may be either MD or IPYNB files. We will also need a configuration file and a topic of contents file. These are YML files.
Step 1: Create a folder with the name “Jupyter Book Demo”. (This will be the GitHub repository name that you will create later in this tutorial.)
Step 2: Uner the folder “Jupyter Book Demo”, create another folder having the name “Book”. All the files will be in this folder.
Step 3: Create demo chapters. These demo chapters can be a markdown file or an ipynb file. An ipynb file is a Jupyter Notebook document. Three demo chapters are discussed below.
Contents of Chapter 1
The contents of Chapter 1 are shown below. You can copy this into a markdown file and save it as Chapter 1.md. Note that these contents are only for demonstration purposes. You can modify these as you wish.
# Chapter 1
This is chapter 1.## Section 1
This is Section 1 of Chapter 1.## Section 2
This is Section 2 of Chapter 1.## Section 3
This is Section 3 of Chapter 1.## Section 4
This is Section 4 of Chapter 1.
Contents of Chapter 2
Similarly, you can create the contents of Chapter 2, and save it as Chapter 2.md.
# Chapter 2
This is chapter 2. This is a demo chapter.## Section 1
This is Section 1 of Chapter 2.## Section 2
This is Section 2 of Chapter 2.
Contents of Chapter 3
The contents of Chapter 3 are created from a .ipynb file. The contents of this .ipynb file are shown below. It is created using Jupyter Notebook.
Creating configuration file
Now, you need to create a configuration file. The contents of this file are mentioned below, and you need to save this as _config.yml. The underscore at the beginning is important here.
# Book settings
title: Jupyter Book Demo
author: Dr. Soumen Atta, Ph.D.
copyright: '2021'# Launch button settings
This configuration file contains different book settings and launch button settings. Note that you need to mention the GitHub repository URL under the launch button setting where “SoumenAtta” is the username of my GitHub profile. You need to use your GitHub profile username here. You can copy this URL when you create a repository in GitHub (discussed later in this tutorial).
Creating topic of contents file
You need to create another file to store the topic of contents and save it as _toc.yml. Here, the underscore at the beginning is also important.
- file: Chapter 1
- file: Chapter 2
- file: Chapter 3
Create a book using Jupyter Book
We have already created the contents of the book (discussed above). Now, it is time to use the Jupyter Book to create a book from these contents. At first, you need to install Jupyter Book on your system using the following pip command:
pip install jupyter-book
Now, open the command prompt in the folder “Jupyter Book Demo”, and execute the following command:
jupyter-book build ./Book
This will create a folder having the name “_build”. In this folder, you will see another folder having the name “html”. Here, you will get the index.html file. When you open this HTML file in a browser, you can see your book. All the other necessary files are also be created after executing the above command.
So, you have already created your book using Jupyter Book, but it is available only on your computer. In the next section, we will learn how to make it available freely over the Internet.
Hosting of your book at GitHub
Now, we will learn how we can freely host our book on GitHub using GitHub pages.
Step 1: At first, you need to sign in to your GitHub account. (If you don’t have an account yet, create one. It’s very simple. You can create a GitHub account using your email.)
Step 2: Create a new repository on your GitHub account. You need to mention a repository name. This is important because the URL of your online book will contain this repository name. Don’t need to create any file such as README.md now. You need to keep the repository empty.
Step 3: Here, I assume that you are using Windows operating system, and Git Bash is already installed in your system. Open the folder ‘Jupyter Book Demo’ and inside it open Git Bash command prompt. Alternatively, if you are using Ubuntu (or, any other operating systems), open a terminal in the folder ‘Jupyter Book Demo’.
Step 4: Now, execute the following commands one by one.
This will initialize the Git repository. You can check the Git status using the following command.
Now, we can use the following command to add files.
git add .
You need to be careful about the dot at the end of the command. It is necessary.
Now, you need to commit for the changes to take place using the following command.
git commit -m “first commit”
The message written within the double-quotes can be anything. In general, for the first commit, we use the message “first commit”, and thereafter, you can use “update”, or, any specific meaningful message.
git remote add origin https://github.com/SoumenAtta/Jupyter-Book-Demo.git
This command is needed for the first time only. Note that here I have mentioned the URL of the repository of my GitHub account, where “SoumenAtta” is the username of my GitHub account. You need to change this URL according to your GitHub account settings.
We can use the following command to publish your local commits.
Now, open Git Bash in the folder “Book”, and execute the following command:
ghp-import -n -p -f _build/html
This will publish your book as GitHub Pages. During these processes, you may be asked to submit your GitHub account’s username and password several times.
If you have followed all of the above steps correctly, then your book should be available in the following URL: https://UserName.github.io/Jupyter-Book-Demo/, where UserName is the username of your GitHub account.