Supercharge GitHub Pages with Jekyll and Travis CI

GitHub Pages are a great way to create and manage a website for your GitHub user, organization, or a project for FREE. In addition to supporting regular HTML content, it also supports Jekyll, a popular static site generator. If you haven’t already, you should familiarize yourself with both GitHub Pages and Jekyll. There aren’t many ways to get a static website up and running faster, but GitHub Pages does come with its own set of limitations. While GitHub Pages is powered by Jekyll, all sites are generated using the --safe option which disallows any custom plugins, according to the Jekyll docs. When I decided to include GitHub repository details from a repository that was hosted outside of my organization, I quickly discovered how limiting the --safe option is. Not to worry, by using Travis CI we will build the site pages on our own and then publish the static site to GitHub Pages.

“Vintage black and white car engine” by RKTKN on Unsplash

What we will cover

  • Using Jekyll build instead of the GitHub Pages --safe build
  • Installing and using the Jekyll-Get plugin to fetch JSON data
  • Organizing the repository for the new build process
  • Setting up Travis CI to build and deploy the site

Using Jekyll build instead of the GitHub Pages — safe build

The first thing that we need to do is replace the dependency on GitHub Pages with Jekyll in the Gemfile. Open the Gemfile, find

gem "github-pages", group::jekyll_plugins
gem "jekyll"
gem "json"
gem "hash-joiner"
bundle install; bundle exec jekyll serve;

Installing and using the Jekyll-Get plugin to fetch JSON data

According to the installation instruction for the Jekyll-Get plugin: “Add this file to _plugins in the root of your Jekyll site.” From the CLI in the root of your Jekyll site:

mkdir _plugins
curl -o ./_plugins/jekyll_get.rb https://raw.githubusercontent.com/18F/jekyll-get/master/jekyll_get.rb
plugins_dir: ./_plugins
jekyll_get:
- data: github
json: 'https://api.github.com/orgs/<ORG_NAME>/repos'
cache: false
jekyll_get:
- data: github
json: 'https://api.github.com/users/<USER_NAME>/repos'
cache: false

Organizing the repository for the new build process

If you are creating a site for a User or Organization, GitHub Pages will only publish content from the master branch. Since we aren’t using the github-pages gem any longer, we’ll need to set up the repository so that the generated site content gets published to master. To solve this problem, I created a release branch and pull-request all of my changes to this branch. I also set the release branch to be the default branch.

master <- generated static site content
release <- Jekyll code to be generated into site
develop <- Branch that contains changes until merged into release

Setting up Travis CI to build and deploy the site

We’re now at a point where the Jekyll config builds without the --safe option, the content is fetched through JSON APIs, and the repository is set up ready for updates to be pushed to the master branch, but GitHub Pages doesn’t know how to build the site any longer. Not to worry, we’ll set up Travis CI to build and publish the generated site to the repository. If you haven’t already, head over to Travis CI and create an account. Once your Travis CI account has been able to sync repositories from GitHub, look for the repository and click the button to active this repository.

touch .travis.yml
language: ruby
cache: bundler
branches:
only:
- release
script:
- JEKYLL_ENV=production bundle exec jekyll build --destination site
deploy:
provider: pages
local-dir: ./site
target-branch: master
email: deploy@travis-ci.org
name: Deployment Bot
skip-cleanup: true
github-token: $GITHUB_TOKEN
keep-history: true
on:
branch: release
language: ruby
cache: bundler
branches:
only:
- release
script:
- JEKYLL_ENV=production bundle exec jekyll build --destination site
deploy:
provider: pages
local-dir: ./site
target-branch: master
email: deploy@travis-ci.org
name: Deployment Bot
skip-cleanup: true
github-token: $GITHUB_TOKEN
keep-history: true
on:
branch: release

Extra Credit

If you are pulling in dynamic content from your GitHub Repos, like star count or number of forks, likely you will want that to be updated regularly. Go back to the Travis CI settings and set up a daily build for the release branch in the Cron Jobs section.

Wrapping it up

This tutorial was intended to show you how I solved a certain problem. If you want to use GitHub Pages to host static sites, likely you will outgrow the github-pages gem rather quickly and need to start using Jekyll Plugins. GitHub Pages is a great service and with Jekyll Plugins and Travis CI there is no limit to the content you can create.

Derek is a software developer based in Atlanta, GA who loves tinkering and working on Open Source projects.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store