Hosting Jupyter Notebooks on a Blog
About this blog
I started this blog in 2015 from some notes I took in Jupyter Notebooks. Starting from these notebooks, it was only a small effort to publish them via GitHub Pages so that they might be of benefit to others.
This post, created way after I initially created this blog, intends to describe how to use GitHub pages to host Jupyter notebooks as blog posts.
GitHub Pages is a service provided by GitHub to host static webpages under the
*.github.io domain. Setting up a GitHub pages is remarkably simple, and only requires creating a GitHub repository with the right name and push some static content to it. See more at the GitHub Pages website and this guide from GitHub.
For example, this blog is backed by this GitHub repository, the page you are reading now is build by GitHub from this repository.
Jekyll is a simple, blog-aware, static site generator perfect for personal, project, or organization sites. Think of it like a file-based CMS, without all the complexity.
Jekyll itself is written in Ruby, however, you don’t need to know any Ruby to be able to use Jekyll. Jekyll itself provides us a few useful functionalities:
- Besides handling HTML files, Jekyll is able to render Markdown to HTML. For example the page you are currently reading is rendered from this Markdown file.
- Liquid as a templating engine, which allows us to reuse a lot of similar functionality like the html head, and the navigation bar at the top. For example, the default layout for content on this blog is defined by a html file build by liquid
- Post’s metadata processing via YAML front matter. For example notice the title and the tags defined at the top of this posts’ markdown file.
To learn more about using Jekyll and GitHub Pages see the documentation on “Setting up a GitHub Pages site with Jekyll”.
GitHub Pages supports a few themes out-of-the-box nowadays. However, this site uses some custom layouting based on Bootstrap components and the various CSS and JS files. For example, the navigation bar at the top of this page is created using Bootstrap, and is defined in this file.
The notebook formatting on this site is based on Jupyter’s CSS files used to export notebooks.
This conversion script is run on a notebook before I push the changes to the GitHub repository. The resulting HTML is written somewhere to the
_posts directory which will be picked up by Jekyll for rendering as a post.
Jekyll GitHub Pages Blog Notebook