Here is a brief summary of how I set up this blog / website using Jekyll on GitHub Pages.
Table of Contents
How GitHub Pages Works
The User Pages default domain and host location (repository name) on GitHub is
username.github.io. User Pages are automatically served over HTTPS from the
As far as I can tell, Jekyll is already enabled by default. In other words, there is no setting that you have to “turn on” in order to get Jekyll to start working on GitHub Pages. Simply by following the directory structure that Jekyll requires will result in the site getting built by Jekyll.
I initially selected the
Cayman theme as I found it the most pleasing among the different themes that are “officially supported” by GitHub Pages. However, it doesn’t come with any sort of navigation bar, so I found the
Cayman Blog theme which does.
The problem is that
Cayman Blog do not use Bootstrap: in fact, they define CSS rules that occasionally conflict with Bootstrap. Consequently, I quit using any pre-defined theme and just used Bootstrap 4 (alpha v6) myself.
Getting syntax highlighting to work required 3 steps.
/css/folder. I copied it over from the
Caymantheme repo, which is allowed per its CC0 license.
- Include the
rouge-github.cssstylesheet in the
To avoid unnecessarily downloading this extra syntax-highlighting CSS on pages without code, I require that any page with code on it to set
use_code: true in its front matter.
To avoid unnecessarily downloading this extra JS file on pages without math formulas, I require that any page with math formulas on it to set
use_math: true in its front matter.
Vanilla Markdown is a bit limited in the formatting that it supports. Hence, GitHub (by default) adds support for extra features such as tables and emoji. The GitHub Markdown cheat sheet can be found here.