In the midst of setting up this blog, I had spent some effort going through the documentation of Jekyll and GitHub Pages to understand how GitHub Pages worked together with Jekyll. I thought it would be a good idea to share my understanding so that someone may find it useful later.
Below are a few references that I found useful.
- Jekyll documentation
- GitHub Pages help
- Build A Blog With Jekyll And GitHub Pages on Smashing Magazine
I assume that the reader is familiar with Git, GitHub and will not be covering instructions to add, commit and push code onto GitHub.
Jekyll, the static site generator
Jekyll is a static site generator implemented in Ruby. A static site refers to a website which consists of complete HTML files that are served directly on request. This means the contents on the website are completely contained in the HTML files. This is as opposed to a dynamic site where website contents are generated by a web application server on request.
Jekyll pre-builds HTML files with content from Markdown files.
To do so, Jekyll has features such as HTML components,
HTML layouts, CSS preprocessing, etc.
The generated static site is completely contained in the
_site folder in the Jekyll project and served from there.
GitHub Pages, the static site hosting service
GitHub Pages is the static site hosting service offered by GitHub.
It serves any static page as long as the file is contained in the
source directory. This directory can be the root directory
gh-page branch or the
master branch, depending on your configuration.
You can specify this in the repository settings.
The static pages do not necessary have to be generated by Jekyll.
GitHub Pages is also able to use Jekyll to generate static site
from the source directory as long as
it is properly configured as a Jekyll project and
serve the generated static pages in the
This is a source of confusion for me
as it did not seem to make sense that the same directory
used to serve static pages directly can also be
used to generate static pages with Jekyll.
It turns out, this is a feature of Jekyll.
Any static file in the source directory is copied
_site folder mentioned earlier without any processing
and can be served directly from there.
This also has the effect of preserving any relative links
between static pages in the source directory,
allowing linking between pages without modification.
From my understanding, when GitHub Pages is activated,
a continuous deployment pipeline is set up in the source directory.
This runs the
jekyll build command to generate the static pages.
The contents in the
_site folder are then served on GitHub Pages.
This pipeline is run on every push to the branch.
To serve up static files in the source directory directly without
any processing by
you may include an empty
Setting up Jekyll
There are instructions for installing Jekyll on the official documentation, hence I will not repeat them here. The components for setting up a Jekyll project is also succintly explained in the documentation. I will cover them briefly.
- Jekyll is implemented in Ruby programming language.
- Ruby libraries are called gems and distributed on RubyGems.
Gem is used to download and install these libraries.
Jekyll is itself a gem. This is analagous to
- Ruby libraries are called gems and distributed on RubyGems. Gem is used to download and install these libraries. Jekyll is itself a gem. This is analagous to
- This file contains the list of gems required for a Ruby project.
For Jekyll, it is also used to manage Jekyll plugins.
This is analagous to the
requirements.txtfile in Python.
- This file contains the list of gems required for a Ruby project. For Jekyll, it is also used to manage Jekyll plugins. This is analagous to the
- I understand this as the environment manager for Ruby, to ensure the right versions of gems are used. This is analagous to virtual environment in Python.
Setting up Jekyll for GitHub Pages
This is where information can get confusing. Jekyll is used to generate static site in general, not specifically for GitHub Pages. GitHub Pages uses a specific version of Jekyll and has limited whitelisted plugins.
You may see suggestions to fill up the Gemfile as follows.
# Gemfile source "https://rubygems.org" gem "jekyll" group :jekyll_plugins do gem "jekyll-feed" end
This allows specifying arbitrary versions of Jekyll
and Jekyll plugins, which may not work with GitHub Pages.
To ensure that your local environment works with GitHub Pages,
you will have to install Jekyll with the
The gem specifies the correct version of Jekyll and also
includes a list of plugins installed in the GitHub Pages environment.
Please specify the Gemfile as follows.
# Gemfile source "https://rubygems.org" gem "github-pages", group: :jekyll_plugins group :jekyll_plugins do end
You may then run
bundle update and
to set up your environment.
bundle exec jekyll new . --force to initialise
the Jekyll project.
You will have to modify the Gemfile again to revert it.
bundle exec jekyll serve to build and serve the
website locally for a preview. It should look similar to
the Jekyll Minima theme website.
You may start working on your website from here.
GitHub Pages plugins
github-pages gem specifies
a list of plugins and their versions.
Do take note that, according to the documentation
and the source code of the gem, there are selected
Jekyll plugins that are enabled, installed and whitelisted.
Any plugins not included cannot be used for Jekyll on GitHub Pages,
even if they work in your local environment,
unless you set up your own continuous deployment process.
At the time of this writing, they are listed as follows.
- Enabled by GitHub Pages and cannot be disabled
- Installed by
- Whitelisted in the source code of
To ensure all whitelisted plugins are available for use in your Jekyll project, you may want to specify the Gemfile as follows.
# Gemfile source "https://rubygems.org" gem "github-pages", group: :jekyll_plugins group :jekyll_plugins do gem "jekyll-include-cache" gem "jekyll-octicons" end
I have covered my understanding of Jekyll, how Jekyll works on GitHub Pages and how to setup the Gemfile to facilitate local development and site preview. With this knowledge, I find that it will be easier for me to set up GitHub Pages for project documentation in the future.
Hope this benefits you too!
Update: below is my other post on Jekyll and GitHub Pages.