Noah Kennedy Based in N.Y.C

Leveraging Jekyll Paginate v2

26 Jul 2021

GitHub Pages, the Jekyll website generator used for this site, generally works pretty well. One of the major upsides is simplicity, but like all simplistic coding tools, there are guard rails in place as well. Simplicity comes at a cost. In our case, only 8 jekyll plugins are supported by GH pages.

Summary

The purpose of this guide is to provide a workaround. By building your site using travis-CI, and deploying the built-up webpage to GH from travis, you can bypass GH Pages inability to build a site using unsupported plugins. This workaround took me ~4-6 hours of rather frustrating work, and if you do not absolutely need the workaround I encourage you to not make your life more difficult. I would also like to note that I’m making this guide after the fact, trying to fill in the pieces, and it most likely won’t be perfect. Please reach out if you find errors in my documentation and I’ll fill them in.

Problem Statement

The state of the problem is this: running the command jekyll build takes the scaffolding that you write, and turns it into a full-fledged website in your _site folder. When you push to your gh-pages branch on GitHub, this build process is done in some fashion by GitHub. Since GitHub Pages only supports 8 plugins, if your site leverages an un-supported plugin, GH pages will simply not know how to use the plugin and therefore your site will break! This is not ideal behavior.

The general idea of the problems is this: instead of having GitHub deal with your build process and fumble your plugin usage, you can use a CI/CD tool like Travis-CI. With a correctly configured Travis-CI deployment, pushing to GitHub triggers a CI job, which runs a script to build your _site folder, and then simply copies the contents of your newly built site into the gh-pages branch. So, the Travis-CI container builds your site for you, and just drops the now-static webpages into GitHub.

I’m not in the business of redundancy (or plagiarism for that matter), so I’ll start by providing the resources I used, and finish by providing some of my notes and code that helped fill in the gaps.

Resources

  1. High level guide to deploying to gh-pages via Travis CI
    • This guide is very useful for understanding the workflow and setting up a framework to build off of, but is lacking some details.
  2. This guide by Lou Marven helped me build out my CI/CD script
    • This guide may not be needed, I used it primarily to fix jekyll-paginate, which I had broken somehow
  3. Travis CI documentation on Github Pages Deployments
    • Travis CI is well done, and I used this to get background information and ultimately inform certain decisions.

Filling in the gaps

After following Resource #1 and reading through the other two resources, your Travis-CI deployment still probably won’t work. The two kinds of issues I came across were dependency/bundler issues, and GitHub authentication issues. All in all, it was a great exercise in debugging, but I’m glad to be done.

GitHub Authentication

The above guides don’t explain how to give the proper permissions to Travis-CI. At a high level, these are the steps

  1. Generate a github Personal Access Token (PAT) here.
  2. Encrypt your PAT using the instructions here.
    • travis encrypt GH_TOKEN="PAT_goes_here_keep_the_parentheses!!!" --add
  3. Define the variable GH_TOKEN in your Travis Repository settings using the instructions here
    • Truthfully I’m not sure if steps #2 and #3 are redundant. The bold can skip step 3 and return later if Auth isn’t working.

After this, GitHub should authenticate properly. If you’re running into errors, you can check if Auth is at fault by going to your GitHub PAT page and seeing if GitHub has ever used it.

Code snippets

There are are a few files that are required for your travis project to successfully build.

  1. cibuild script, a simple bash script that does all the heavy lifting and generates/pushes your website.
  2. travis.yml file, which gives some directions and configures the job that happens when you push to Travis.

The guide by Anatoliy Yastreb fills these in, but in my opinion misses some steps. I can’t say my code is better - I think it’s more redundant - but these are my files.

cibuild script

#!/bin/bash

# skip if build is triggered by pull request
if [ $TRAVIS_PULL_REQUEST == "true" ]; then
  echo "this is PR, exiting"
  exit 0
fi

# enable error reporting to the console
set -e

# cleanup "_site"
rm -rf _site
mkdir _site

# clone remote repo to "_site"
git clone https://${GH_TOKEN}@github.com/noahfkennedy/noahfkennedy.github.io.git --branch gh-pages _site

# build with Jekyll into "_site"
bundle install
bundle exec jekyll build

# push
cd _site
git config user.email "noah.kennedy1@gmail.com"
git config user.name "Noah Kennedy"
git config --list 
git add --all
git commit -m "Travis #$TRAVIS_BUILD_NUMBER"
git push --force origin gh-pages

travis.yml file

language: ruby
dist: trusty
rvm:
- 2.5
before_install:
  - yes | gem update --system --force
  - gem install bundler:2.2.24
branches:
  only:
  - master
before_script:
  - chmod +x ./script/cibuild
after_script:
  - git config credential.helper "store --file=.git/credentials"
  - echo "https://${GH_TOKEN}:@github.com" > .git/credentials
script: "./script/cibuild"
exclude:
- vendor
sudo: false
env:
  global:
  - secure: my_variable_goes_here_but_travis_fills_this_in_for_you!
  jobs:
  - USE_NETWORK=false
  - secure: "<you can also put encrypted vars inside matrix>"

Running the script

In order to kick off a Travis build, you need to push to your master branch.

Within the travis.yml file, you set the branch to run on, so you can make this any other branch. I like master, because I only really want to do major builds. The base plan of Travis comes with a limited number of credits - I used about 25% of mine just trying to get it to work - so I would rather not waste all that compute.

Conclusion

Ultimately, you will probably need to do your own debugging. In a way, it was a fun exercise in debugging, something I don’t need to do as much at my current job. If you notice any inconsistencies or see any spots in my code that are wrong (I’m sure there are many), feel free to reach out at noah.kennedy1@gmail.com and I’ll do my best to modify this documentation.

Related posts