Jekyll and GitHub

A while ago I wanted to setup a second blog for some fiction. I could have set up another blog at WordPress or hosted it locally, but I didn’t want all those dependencies. Instead, I went with Jekyll, which generates static HTML files from a directory structure. So no database, no heavy server backend, just a thing serving static files.

When it came to hosting, I noticed that GitHub now offers Pages, which is pretty amazing since they even support DNS CNAMEs, which means I can take my domain and just create an A record in DNS that points at GitHub. Unfortunately, the documentation on GitHub isn’t too great, so here’s the recap:

  • If you don’t use their page builder tool but prefer manual pages, create a new branch in your git repository, called gh-pages
  • To this repository, you can upload your Jekyll hierarchy and they build it automatically for you. If you do this the first time, it may take some time to show up. GitHub says 10 minutes, but it took an hour for me. After the initial push is up though, further pushes are published instantly
  • Even if your repository is private, published pages will be public
  • The downside of uploading Jekyll repositories is that GitHub doesn’t run plugins

The last point was an issue for me: I have plugins to build Tag/Category pages and to minify CSS, and GitHub won’t run them. Okay, no biggie, I’ll just build them locally. Just check out the gh-pages branch, Jekyll into it, and commit changes, right?

Well, Jekyll unfortunately cleans out the target directory when it builds. That actually makes sense, since we don’t want any old garbage in there, but it unfortunately also deletes the .git folder.

After searching a bit, I found that git has an amazing feature: You can specify --work-tree to tell git that the Working Directory is in a different folder than the .git folder. I don’t know why they put in that feature as it seems so niche, but I would like to express sincere gratitude, it saved me here.

I structured my git repository like this:

  • master branch contains the Jekyll site and is checked out to ~/MySiteSource
  • gh-pages branch starts out empty and contains the built site. It is checked out to ~/MySite/_site, but I moved the .git folder to ~/MySite

Inside the ~/MySite directory (which is NOT part of the git repository, but contains the .git folder for gh-pages), I have a little shell script (or batch file if you’re on Windows):

cd ../MySiteSource
jekyll --no-auto
cd ../MySite
git --work-tree=./_site add .
git --work-tree=./_site commit -m "built site"
git --work-tree=./_site push origin gh-pages

Simple yet effective. So we go into MySiteSource, tell jekyll to build the site (_config.yml sets the destination to ../MySite/_site), then go back to MySite and use the --work-tree option to commit the gh-pages branch.

July 29th, 2012 in Development, Entertainment | tags: , ,