Using Jekyll to Build GitHub Pages

Introduction

GitHub Pages is a fantastic way to host your personal website from your GitHub repository – it is free, convenient while provides much richness in customizing your own style. In this post I will first guide you how to render your repository into a website. Then I will discuss a bit more on how to use Jekyll to preview posts locally before pushing the changes to GitHub.

:pencil: For complete beginners, I would recommend a training course on GitLab, a great resource to get to know Pages.

Jekyll and GitHub Pages

Jekyll is a built-in engine behind GitHub Pages. It is a popular static site generator written in Ruby, which can transform plain text (e.g. Markdown files) into static websites.

All we need to begin with in our repository are a _config.yml file and an index.md file. The file structure of the hosting repository would look like:

|--
  |-- _config.yml
  |-- index.md
  |-- _posts/
    |- yyyy-mm-dd-<title>.md

The index.md file is the content shown on the homepage. The _config.yml file (example) describes the Jekyll configuration. With these being set, we are all good to post our blog.

Getting Started - Initializing GitHub Pages with Jekyll

First create a GitHub repository and enable Github Pages in Settings following this guide.
Create an index.md file with the content to be shown on the homepage

Create a _config.yml file with the following content:

title: Your awesome title
author: GitHub User
email: your-email@domain.com

description: > # this means to ignore newlines until "show_excerpts:"
  Write an awesome description for your new site here. You can edit this
  line in _config.yml. It will appear in your document head meta (for
  Google search results) and in your feed.xml site description.

show_excerpts: true # set to false to remove excerpts on the homepage

# Build settings
markdown: kramdown
theme: minima

# Plugins
plugins:
  - jekyll-feed

Commit the changes to master and that’s it. Now we can visit our website!

Note here we use the minima theme, which is one of the default themes supported by GitHub Pages. We can change the theme in Settings. However, if we want to use other themes, we may need to install it or use remote_theme.

Let’s say we want to use the minimal-mistakes theme. Since we just want the changes to be effective on Pages, we will use the remote_theme way. All that needs to be modified is the _config.yml file:

Comment out all other themes and add

remote_theme: mmistakes/minimal-mistakes

Add plugin jekyll-include-cache to the plugins array
Commit changes and refresh the website

Installing Jekyll on Ubuntu

Enabling Jekyll on GitHub is as simple as mentioned above. However, if we want more advanced features, like previewing our post locally and troubleshooting possible failed builds before pushing the changes, we need to install Jekyll on our local machine.

`bundler` and `gem`

So how do we install Jekyll? Jekyll is Ruby based and Ruby uses RubyGems to install and manage packages. gem is the command-line tool. A gem is also referred to a Ruby library and gemfile is used to describe gem dependencies for Ruby applications. Bundler is the most common tool to manage gem dependencies. We can analogize these concepts with Python as follows. It is not exactly the same, but close:

Python	Ruby
`pip`	`gem`
`anaconda`	`bundler`
`requirements.txt`	`gemfile`

Installation

Installing Ruby
Ubuntu 16.04 should have pre-installed Ruby, but my experience told me it would not be able to compile Ruby extension modules. There will be error messages like "Failed to build gem native extension". Therefore, we need to install ruby-full:
```
sudo apt-get install ruby-full
```
Installing Bundler & Jekyll
At this stage, we know Bundler, or Jekyll is actually a gem. Bundler is the gem to manage gems. It is best to avoid installing Ruby gems under root directories. We can set up the installation path under $HOME. First append the following to ~/.bashrc:
```
# Install Ruby Gems to ~/gems
export GEM_HOME="$HOME/gems"
export PATH="$PATH:$HOME/gems/bin"
```
Then run the following in Terminal
```
source ~/.bashrc
gem install bundler jekyll
```

Setting up Jekyll Locally

Once we have installed Jekyll, we can set up Jekyll configuration in our repository. Clone the above github repository locally (find my git tutorial here). Then

Create `Gemfile`

Create a Gemfile file under the repository’s root directory with the following content:
```
source "https://rubygems.org”
gem 'github-pages', group: :jekyll_plugins
```
Install github-pages gem by running:
```
bundle install
```
Gem dependencies will be installed at ~/gems. A Gemfile.lock file will also be generated under the current path.

Installing other gems (if needed)

Whenever we need to install other necessary gems

add them to Gemfile

gem 'jekyll-include-cache' # if we use the `minimal-mistakes` theme

execute
```
bundle
```

Build local Jekyll site

Build project
```
bundle exec jekyll serve
```
The jekyll serve command builds the site and run a local web server at http://localhost:4000. The bundle exec prefix says to run commands under the environment set in Gemfile.
Preview the local site at http://localhost:4000.
Press Ctrl+C to stop the process.

:pencil: After built, a folder _site/ will be generated. This is where Jekyll outputs HTML files converted from our posts etc. Therefore, it should not be staged in git and needs to be added to .gitignore.