In the process of building this site and I had to figure out many things, one of the most important being of course, deploying. When deciding to deploy a site one of the most important things to decide is where to host it, I chose to use github pages, like any cheap-skate developer with a github account would. This seemed like it was going to work out great, just make changes and github will build and deploy to github pages for me! What could go wrong?


Custom plugins and any other ruby gems. Github doesn’t allow for the use of non-standard jekyll in their github pages if you want them to build it for you. They list on their site that it’s due to security reasons, which is fine, but what’s a developer to do? Well, you can build it yourself and deploy it to a /docs subfolder in your project, or checkout master in a gh-pages branch and then remove everything that isn’t part of your generated site. Both of those are messy code wise and git history wise. I’ve found a better way.

git subtree

git push origin :gh-pages
git subtree push --prefix _site/ origin gh-pages

Instead, delete the remote branch, and push your compiled site as an orphan branch! This keeps your history clean and prevents you from checking in un-needed files, but not all is well yet. First you still have to change your baseurl if you use a different one locally, and also you have to be sure that the build folder is not in gitignore. This means you have to be sure to not accidentally check your built site in and also to not check in your incorrect config.

The alternative I’ve found is having a _config.yml and a _config.yml.example and only checking in the example file to git. In my case as Kimchu Chingu is open source I want anyone to easily clone and build the repo, so a master config is important. I also have a .gitignore-publish file that I use when I deploy. This requires you to rename files, then once pushed, rename them back which is messy and time consuming as well as error prone. To minimalize this, I made a simple script that does it all and cleans up to be sure that nothing weird gets checked in.

mv .gitignore .gitignore-local
mv .gitignore-publish .gitignore
mv _config.yml _config-local.yml
mv _config.yml.example _config.yml
bundle exec jekyll build
git add -A
git commit -m "publish"
git push origin :gh-pages
git subtree push --prefix _site/ origin gh-pages
mv .gitignore .gitignore-publish
mv .gitignore-local .gitignore
mv _config.yml _config.yml.example
mv _config-local.yml _config.yml
git reset HEAD~1
git stash

Since I use this script in two places and didn’t want to copy it include any changes I made a repo for the script alone. Then I add it to jekyll projects that deploy to github pages using

git submodule add

This prevents code reuse and allows easy updating in the future. Once you have the module pulled in, just run sh JekyllDeploy/ and your site should build and be deployed!

Happy deving!