(This tutorial is cross-posted on my github.)
Jupyter Book vs Jekyll for Github Pages
Both will generate static site for you, which means you can write your pages in markdown and they will built your html pages based on the layout settings.
(+) Native support for jupyter notebook file (ipynb). While you can put your ipynb
file to Jekyll (see the example from my page here), it needs to be converted to html first before Jekyll converts it to another html with the predetermined layout settings.
(+) Easier to install since you only need to install jupyter-book
and ghp-import
packages in your python environment. Less headache for Windows users since you don't need to install Ruby and/or Linux distribution.
(-) No customized template available for Jupyter Book. Jekyll has plenty of themes (check them here).
If you still wish to build Github Pages using Jekyll, check my tutorial and my page.
Live Version
Check the live version of my Jupyter Book here.
Jupyter Book Tutorials
Assumptions
You are already familiar with:
- git
- command line
Steps
The official tutorial from Jupyter Book covers pretty much all of the required steps. I added some notes based on my experience:
-
Install Jupyter Book
Starts from this page. Make a new environment, solely for making jupyter book and install the package there. I recommend to use Python 3.7.
However, there is a known incompatibility for notebook execution when using Python 3.8.
-
Tweak Some Files
Follow the instructions from the beginning until the "Add it to your Table of Contents" part in "Create your own content file" page. I repeatedly encountered build failure which coming from Github Actions trying to build the references section in the later step. Remove
references.bib
and comment out the line where it includes references in_config.yml
file. Proceed to the next steps, starting from "Re-build your book". -
Prepare
gh-pages
branchWhen you finally get to "Publish your book online with GitHub Pages" part, you will need to setup
gh-pages
branch (step 2). By now, your jupyter book is already available in your repository but not yet deployed as a page. Open your repository in browser (i.e.https://github.com/azukacchi/notebooks
) then create a branch calledgh-pages
, which will contain all files as yourmain
branch. You should have two branches (main
andgh-pages
) in your repository. Finish the remaining steps.Note that you don't need to make changes to the
gh-pages
branch, only themain
branch. Any changes made to themain
branch will be applied byghp-import
package by overwriting all files ingh-pages
. Thegh-pages
is solely used as the source for your Github Pages.
Notes
When you want to update your book, you should always make your changes to the main
branch:
git add ./*
git commit -m "update xxyyzz"
git push
Then rebuild your book, i.e. for my notebooks
repository:
jupyter-book build notebooks/
ghp-import -n -p -f notebooks/_build/html
Top comments (0)