Creating websites using jupyter{book}
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.
Structuring the jupyter{book}
The main structure of a jupyter{book} looks something like this
- 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.
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.
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.
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.
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}.
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.
This command builds your notebook based on the execution settings in your config file.
If you have notebooks and information related with it and want to keep the same outputs, change this particular setting in the config file.
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!