Setting up a jupyter book

Troubleshooting the page and getting it to appear properly in GitHub Pages took a little while. I’ll try to document the successful steps here.

I am using jupyter-book with the cookiecutter template, and deploying it to be public on GitHub Pages. While I don’t strictly need executable code at the moment (and so could use an alternative like a “hugo” book theme), I may change my mind later.

Considerations before starting

Some possible considerations before starting:

• With this solution, your resulting course notes will be world-readable.

• You need a GitHub account (or similar). My university GitLab does not permit Pages. You may need a Pro account which is a charged service, though an education license at GitHub works.

• I also use Latex exam class for course notes, which allows me to create an exercise sheet with an answer key in the same file. This is no longer possible with the use of markdown. Formatting is also simpler. So this is a potential disadvantage.

Some general references:

• JupyterBook.org: Create your first book to simply work with the jupyter book

• JupyterBook.org: GitHub Pages. However if you start with the generic jupyter book and edit for a while, then decide you want to publish it on GitHub pages, you may need to do some back-editing. Instead, the later instructions for generating a book with built-in push-to-Github features are where I’ve started.

• cookiecutter-jupyter-book (repository) - this is the flavour of jupyterbook which includes a GitHub Actions workflow, specifically for deploying the jupyterbook you’ve created onto github. At time of writing (2024), this appears to be somewhat out-of-date, so there were some necessary edits detailed below.

My file structure

to help make sense of the rest of this

This is an example of where a jupyterbook (in messfern_cb/) lives on my computer and the structure generated by cookiecutter (in coursebook-messfern/, a level above the jupyter book).

My local git repository is coursebook-messfern/, mapped to a remote repository at http://github.com/ifmeo-hamburg/messfern/.

Example file structure for a different course, `OzMess’.

OzMess-UHH/               # One directory per course
├── 2023-OzMess/          # Sub-directory per year
├── 2024-OzMess/          # Sub-directory per year
│   ├── README.md         # describes where data came from
│   └── sub-folder/       # may contain subdirectories
└── coursebook-OzMess/    # not within a year since it is using git for versions
    ├── .git/
    ├── .github/          # this contains workflows for GitHub Actions
    ├── .gitignore        # Your .gitignore file
    ├── CONDUCT.md
    ├── CONTRIBUTING.md
    ├── LICENSE
    ├── ozmess-cb/        # the Jupyterbook folder
    │   ├── _build/       # the generated html
    │   ├── _config.yml   # configuration file for the book - check this after generating
    │   ├── _toc.yml      # where you will create your table of contents
    │   ├── contend.md    # a markdown file in the main directory
    │   ├── logo.png      # if you have a special logo to use
    │   ├── notebooks.ipynb   # a python notebook
    │   └── references.bib # a bibliography file in Latex format    
    ├── README.md
    └── requirements.txt