Producing a suite of HTML files using Jupyter Book
Contents
Producing a suite of HTML files using Jupyter Book¶
The webpages you can produce with Jupyter Notebook are fairly nice and clean and do everything basic you would want. However, if we are going to the trouble of producing HTML content, it would be nice if we can make use of that to its fullness and produce something that looks and works nicely as a website.
The answer to this is Jupyter Book. This is a community-driven open-source project that is an extension to Jupyter Notebook. It is designed to take your Jupyter Notebook files (and it will also take other formats) and knit them together into a ‘proper’ website. It also uses a sort of extension to Markdown, called MyST Markdown (I don’t know much about this, other than it allows you to do some more fancy things as we will see on the next page), giving you even more options and control.
I will talk through some of the processes of building a Jupyter Book website here, but you should absolutely consult the actual project’s webpages and its really pretty thorough tutorial pages as your guide (https://jupyterbook.org/en/stable/intro.html).
Installing Jupyter Book¶
Jupyter Book does not come as part of a standard package in, say Anaconda or the Jupyter Project, and has to be installed through the command line. Open a command window and type,
pip install -U jupyter-book
or you can use the Anaconda prompt, typing,
conda install -c conda-forge jupyter-book
This should install the package in a few minutes.
Warning
The installation initially did not work on my laptop - I got multiple warnings about conflicts and then it would just hang for hours not doing anything. I believe this to be a localised problem in that after many years my Python distribution is quite messy, but I wanted to mention it in case anyone else has the same issue. The solution for me was to first enter a virtual environment (I didn’t really know what this was until I needed to use it, but it is simply one line of code in the command line) and then it installed fine. I then have to enter the virtual environment whenever I want to use Jupyter Book (but again, it’s just one line of code). Hopefully for those of you who look after your computers properly this will not be an issue.
Creating a template¶
To my mind, the simplest way to create your own set of webpages is probably to create the default, template book and then move all of your material into it. To do this, in your command prompt navigate to the directory where you want the documents to go and then type,
jupyter-book create mynewbook/
This just takes a few seconds to run. If you now go to your normal file directory you will see this new folder called mynewbook has been created. If you look inside you will see a few files have been created. Most of these are example documents that have been created to form the basis of the book. Two important files are _config and _toc, and it is worth opening them in a text editor to see what’s inside them. The _config file contains a number of details used to build the book, including an overall title and any libraries that you may wish to include. The _toc file contains a list, in order, of the files that will be included in the book.
The next stage is to build the book, in other words create the set of HTML pages. To do this go back to the command line and type,
jupyter-book build mynewbook/
After a few seconds this will say it is completed. If you look back in the mynewbook file directory you should see a new folder has been created called _build. Open this and then the html folder, and you will now see a set of HTML pages (and a few other bits and pieces that we won’t worry about). If you open the index HTML file in your chosen web browser you should see a fairly minimal website, not hugely different from these pages (since these were also made using Jupyter Book). Take a few moments to explore this short book. Key components to note are:
The title, logo and table of contents down the left-hand side.
The content itself in the main panel.
The links forwards and back at the bottom of each page.
This is a very minimal book, but hopefully you can already appreciate that many of the problems we found in creating a large multi-lecture webpage have been solved here, and it produces something that looks really quite smart.
Now we can go ahead and use this to create our own book.
Creating your own Book¶
As a starting point, I will assume you have multiple Jupyter Notebook files all ready to go. We will go into some more details of how you can make these more fancy in the next page, but we’ll just work with whatever you have for now. To be completely clear, these do not need to have any hyperlinks buried into them - Jupyter Book will sort all that out for us - but are simply a set of self-contained files with all the content you want in them.
In your regular file directory, drag all of your pre-prepared Notebook files across to the mynewbook folder (or use the command line, whatever you prefer). Now open the _toc file. Lines 6-8 currently read:
chapters:
- file: markdown
- file: notebooks
These two files, markdown and notebooks were simply the names of the files Jupyter Book was using to build the webpages. You want to replace (and append) this with the list of files you have. So for example if you called your files chapter1, chapter2 and chapter3, you’ll want to write,
chapters:
- file: chapter1
- file: chapter2
- file: chapter3
You’ll also see line 5 currently reads,
root: intro
This will be the landing page for your webpages. You may well not have created this yet, but is a good idea. (You could just go straight to chapter 1, I suppose, but I think it is good practice to have some sort of index page). This can be fairly brief and include any important details around organisation of your course, perhaps a summary overview of the material, etc, and can again be written as a Jupyter Notebook file. Replace intro on this line in _toc with whatever you called your file.
Now you can delete the files from the template book that are no longer needed (markdown, notebooks,…) - both those in the mynewbook directory and those in the html sub-directory (otherwise things might get confusing).
Note
This potential source of complications in needing to delete files could of course be avoided by starting a new book from scratch. This is perfectly possible and you can read more about it on the Jupyter Book tutorial pages, but I personally find it easiest to do it this way to avoid any silly mistakes in the format of the files.
Now go to the _config file. You will want to change the title and author entries, and perhaps use your own logo image. To ensure all the mathematical content will work, you will also need to add in the following lines at the end of the file,
parse:
myst_enable_extensions:
- amsmath
- dollarmath
Now you can build your book. Again, in the command line type,
jupyter-book build mynewbook/
and after a few moments it should all run and tell you your HTML files are ready. Once again, go into the _build/html folder and check that everything looks as it should.
Creating a PDF¶
As when I talked about generating the single page, you may still want to have PDF copies of notes to use fo handouts, etc. Jupyter Book has a couple of methods for achieveing this, though as the online guidance says, it is still in development. Rather than re-hash it all here I will simply suggest you click here to go to the guidance pages and follow the instructions there. I will simply add that I have had mixed success with this automated process, but the basic alternative to simply download each page as a PDF and then stick them together in something like Adobe is always available.