Using plugins with Jekyll and gh-pages

As you may have noticed, this website is powered by Jekyll and hosted on GitHub Pages. It’s fun, it’s easy, it’s dynamic, but there’s a catch - plugins.

Indeed, GitHub Pages works in so-called safe-mode, which only allows for plugins verified by GitHub. Often, you find yourself using plugins you or others have developed, to accommodate for very specific demands : these will unfortunately be rejected by gh-pages. The solution is then to build the site locally, which I resorted to for a while (as long as I needed to use a certain gallery plugin) but is honestly a bit sad. You completely lose the “git push and your site will be built automatically” functionality that makes the Jekyll/Git combo so powerful and distinct.

Anyway, here’s the work-around I used to solve that problem.

Two branches instead of one

I created another branch, static_build, on top of the master branch gh-pages. All the markdown files and work in progress goes into static_build, while the final HTML built version goes in gh-pages, which is then the basis for my website. This system later allowed me to keep a track of the plugins I used and the way I implemented them (my memory isn’t that great…) when I switched the two branches around to get back to the “dynamic” mode.

Commit and build

The workflow is roughly the following :

git checkout static_build
# write posts, edit website
git commit -am 'added a fancy new article'
# let a custom function do the rest
sitebuild

And the custom function I created is (you can put it in your ~/.bashrc for instance) :

sitebuild(){
    bundle exec jekyll build
    git checkout gh-pages
    git rm -r --ignore-unmatch *
    rm -r .temp
    mkdir .temp && mv * .temp/
    mv .temp/_site/* . && rm -rf .temp && rm -rf _site/
    touch .nojekyll
    git status
    git add .
    git status
    git commit -am "update"
    git push --all origin
    git checkout static_build
}

Granted, it’s ugly, and it will mess your folder organization up if you don’t call it at the right time, but otherwise it gets the job done… Essentially you build the website, switch to gh-pages, delete everything but the content of the built _site folder, add a .nojekyll so that GitHub doesn’t try to build it again online, then commit and finally push everything. To avoid (more) confusion, you’re also brought back to your developer branch at the end.

Going back to “dynamic” mode

If you want to return to the proper way of using gh-pages, you can simply rename your branches, using the command git branch -m <old> <new>. Remember that your main branch must be named gh-pages (or master if you’re working in project mode on GitHub). Be sure to redirect the tracking of your local branches to the appropriate remotes by doing : git branch <name> --set-upstream-to <remote/branch>.

That’s all. I hope this has been useful (I might have to go back to doing things this way in the future…), and if you have a better solution, please post it in the comments!

comments powered by Disqus