GitHub Pages: Leveraging unsupported Jekyll Plugins
GitHub Pages, the Jekyll website generator used for many personal sites, 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.
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, and if you do not absolutely need the workaround I encourage you to not make your life more difficult. If you want practice using a super cool CI/CD tool like Travis-CI, then keep reading!
I would also like to note that I’m making this guide after the fact, trying to fill in the pieces, and I probably missed something! Please reach out if you find errors in my documentation and I’ll fill them in.
Problem Statement
Running the command jekyll build takes the scaffolding that you write, and turns it into a full-fledged website in your _sitefolder. When you push to your gh-pages branch on GitHub, GitHub builds your site for you. Since GitHub Pages only supports 8 plugins, any un-supported plug-in will crash your build process! This is not ideal behavior.
The general idea of the solution 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
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.
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
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:
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.
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.
- cibuild script, a simple bash script that does all the heavy lifting, build your site and then pushing to GitHub.
- travis.yml file, which tells Travis-CI exactly what to do when it receives a
git push
The guide I linked by Anatoliy Yastreb fills these in, but in my opinion misses some steps. I can’t say my code is better — I think there is some redundancy that could be removed — but it works.
CIBuild Script
The only changes you need to make above are your Git Repo Name on line 13, your Git Email on line 19, and your Git Name on line 20. Anything else is preference.
travis.yml file
In the travis.yml file, running the command I mentioned above to encrypt your GH token should fill in line 22.
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, I can modify the yml file to build when I push to any other branch I like. I prefer 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, 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.
