How to get around the jekyll-pagination-v2 limitation of GitHub pages with CircleCI
Github pages is a damn modern marvel. You can put together a basic website hosted for free from a jazillion templates available on the internet. Buy a domain name. You’re set. Push up changes to the source on GitHub and they regenerate the site. AMAZING. Almost as good as geocities was. But using GitHub pages the way GitHub suggests has some limitations. Jekyll has soooo many helpful plugins that you can use outside of the oens offered on GitHub pages. Such as the jekyll-paginate-v2 plugin. And if you want to use the jekyll-paginate-v2 plugin with GitHub pages you’re out of luck! They don’t support it. Which means you can’t do pagniation of collections - a very useful feature when you want to build more complex websites or blogs using jekyll. But we can work around this with a bit of scripting and CircleCI.
If you want to know all of the technical details of the script then check out the blog post by Sangsoo Nam which inspired me to automate this. It’s really well written and explains the mechanics better than I could. But to catch you up we basically configure our GitHub pages site to use two separate branches. One branch will contain the source code of our jekyll site. Typically the branch would be the defaul master branch, and we push our site changes to this branch. This will kick off a job on CircleCI which uses the latest version of jekyll and all of it’s available plugins to generate the site source code. Then it automagically pushes that generated source code back up to our GitHub pages branch which is typically gh-pages. Then the GitHub repo is configured to serve up the freshly baked source code right from the CircleCI oven to your users. So now we’re not limited to using the hosted version of jekyll and limited set of allowed plugins. WE CAN USE ANYTHING. FREEDOM.
And since we can use anything I decided to add some testing to the site. Before I had the testing I didn’t realize how many things were broken. A ruby gem called html-proofer found over 250 errors with my site! Yikes. Even some very broken stuff that broke the site for search engines which hurts the SEO on the pages. Now that we’re running on CircleCI we can add simple checks to the generated site before we deploy it. So first I used html-proofer which lints all of sites html structure. Finding broken html structure and bad practices. It even has an option to lint your opengraph structure. Another thing I wanted to check was some generated json files that I use as an API. I use find to create a list of all the json files in the site source. Then I pass them into another ruby gem called jsonlint which makes sure the json structure is corect before the site gets deployed. At the end you can see that it makes an API call to CloudFlare to purge the cache. You don’t need to add this but CLoudFlare is really good and can help speed up the site. They have a free tier that will work for pretty much any GitHub pages site.
So all the magic here is thanks to CircleCI. Basically when we push a commit it spins up a CI job that performs the deployment steps outlined win Sansoo’s blog post. Which you know about now since you went to read it. But to give the tl;dr of the whole process again: When we push a commit to GitHub it triggers a job on CircleCI. Using the config above in the site repo CircleCI will checkout the code from master. Then compile our fresh jekyll website using the latest version of jekyll and whatever plugins we need. In my case it was the jekyll-paginate-v2 plugin. Then it runs tests to make sure the site structure and json APIs aren’t broken. Finally, that freshly compiled site gets pushed back up to the gh-pages branch where GitHub will serve it up on GitHub pages. Cool.
Other than all that it’s still pretty close to the original script. Except now the whole process is automated, so no need to manually push code twice.