Creating websites using jupyter{book}

JupyterBook

Overview

As a part of GSoC’21, I did migrated the old webiste of IOOS to a jupyter{book} format which made the website more appealing as displaying the notebooks got even better.

In this blog, we will be looking at how to create a jupyter{book} website.

Jupter{Book}

Jupyter Book is an open source project for building beautiful, publication-quality books and documents from computational material. This allows us to publish notebooks and makes graphs, charts and markdown files easier to read on a website.

Installing Jupyter{book}

To install jupyter{book} on your system, run the following command.

CMD installation of jupyterbook using pip

Structuring the jupyter{book}

The main structure of a jupyter{book} looks something like this

The structure of a jupyter{book}

• The content folder consists of all the notebooks that are there in their respective folders (aka. chapters).
• The images folder contains all the images we need in our jupyter{book} (to be ref. as JB).
• The _toc.yml has the basic structure of how we want our notebook to be.
• And the _config.yml files contains the configuration of our JB.

The Content Folder

In the content folder, it is better to stay organized as while creating the _toc.yml, we will not have any issues. The content folder should ideally look like this.

A basic structure for the “content” folder

Look at the following folder structure I created for IOOS Code Lab to get a better understanding of how the content folder should look this.

notebooks_demos/jupyterbook/content at master · ioos/notebooks_demos

The _toc.yml file

The _toc.yml is basically the table of contents for our webpage. It will look this . This is important as how we want our webpage to be in a specific format ie. it orders the pages.

A basic _toc.yml format

Here is a link to the _toc.yml file I created for IOOS. It gives a clear understanding at how to create the toc file for various chapters.

notebooks_demos/_toc.yml at master · ioos/notebooks_demos

The _config.yml file

The config file is another important file that we would want to make changes to in order to “configure” -pun intended- our jupyter{book}. A basic configuration file looks like the following code.

This config file contains all the configurable options that can be changed for a jupyter{book}. If you don’t want to have such a big file, you could write your own config file with what you only want to have control over. The other configurable options will be defaulted to, in-case you don’t include them in your config file.

You could only have the “Book Settings” and the “Execution Settings” enabled on your config file, as these are the most important settings to your jupyter{book}.

notebooks_demos/_config.yml at master · ioos/notebooks_demos

Building the Website

Once you are done with having all the necessary content in place, we can start building the website. to build the website, run the following command in the terminal.

Command to build the website

This command builds your notebook based on the execution settings in your config file.

Execution settings for building the website

If you have notebooks and information related with it and want to keep the same outputs, change this particular setting in the config file.

Execution settings for building the website

Post-Build

Once you build the website, you can click on the link that is generated and open it. This is built locally. If we wanted to host the website on GitHub pages or any other website, we would need to add some other files to our code. I will be covering this in the next blog!