Custom Jekyll plugins on github-pages

Github-pages is fantastic, they provide free hosting for static sites, or Jekyll sites that stick to the list of whitelisted gems. Traditional wisdom is that if you want to use Jekyll with plugins Github doesn’t allow, you need to host it on Amazon’s S3, or some other platform that isn’t as restrictive as github.

I am cheap, and don’t want to pay for hosting, so instead I chose to build my site in Circleci and have CircleCI push the static files up to Github. To do this, I needed to create a branch (or it could be its own repo) to store the static files generated by Jekyll. I chose to use master for static files, and develop for all the Jekyll code because github’s user-pages must be on the master branch.

The first step is just to get your site building in CircleCI.

# .circleci/config.yml
version: 2.0

jobs:
  build:
    docker:
      - image: circleci/ruby:2.4.3
    steps:
      - checkout
      - restore_cache:
          keys:
            - v1-bundle-\{\{ checksum "Gemfile.lock" \}\}
      - run: bundle install --path vendor/bundle
      - save_cache:
          key: v1-bundle-\{\{ checksum "Gemfile.lock" \}\}
          paths:
            - vendor/bundle
      - run:
          name: Install Prerequisites
          command: "sudo apt-get update; sudo apt-get install -y rsync"
      - run: 
          name: Build Site
          command: JEKYLL_ENV=production bundle exec jekyll build
      - store_artifacts:
          path: _site
          destination: /
      - run:
          name: Deploy
          command: _scripts/deploy.sh

This simple CircleCI 2.0 config will build a Jekyll site in ruby 2.4.3, store the static files as build artifacts, cache the installed gems to speed up future builds, and finally run a script to deploy it.

#!/bin/bash
# _scripts/deploy.sh

DEPLOY_DIR=$(mktemp -d)
BUILD_DIR=$(readlink -f "./_site")

# clone target repo to a temp dir to ensure no name collisions
git clone $CIRCLE_REPOSITORY_URL $DEPLOY_DIR
cd $DEPLOY_DIR

# verify clean repo
git fetch origin
git checkout master

# configure git committer
git config --global user.name CI
git config --global user.email ci@example.com

#copy compiled site from artifacts
rsync -a --delete --exclude=.git $BUILD_DIR/ .

# commit changes
git add -A
git commit -m "Deployed in CI: $CIRCLE_BUILD_URL"
git push origin master

# ping search engines with new sitemap
curl "http://www.google.com/webmasters/sitemaps/ping?sitemap=https://www.example.com/sitemap.xml"

The script simply clones the repo, checks out the master branch, syncs it with the output from the build step, and commits it with a link to the build on CircleCI.

After creating a checkout key in CircleCI with write access to your repo, you are now free to use any gems you like and Github will host it for free.

As an extra bonus you can add extra features like spell check, HTML validation, or a safety check to verify that you don’t accidentally add commits to the wrong branch.