I have settled on GitHub Pages and Jekyll Bootstrap as the fastest way to get started with blogging in a way that gives me some reasonable control over the formatting and design process. There are several things that I like about this combination:

  • GitHub handles the source, backups, hosting and scaling
  • Jekyll adds the structure to make it viable as a blog (and serves locally for prototyping!)
  • Markdown is fast and easy to write for formatting purposes

I am pleased with how easy it is to get started:

git clone
git remote set-url origin
git push origin master

I had originally started configuring my GitHub Pages repo a few months ago and the code was slightly out of sync with the JB repo. I want to be able to pickup changes from the JB upstream master, so I configured that:

git remote add upstream
git pull upstream master
git push origin

In the process of configuring my blog, I found the following links helpful:

Eric’s blog has several tricks for integrating with various other web services like social sites and what not that seems like it would be useful for increasing engagement with posts.

Configuration Details

I like the modern fonts and white-on-black look of the Hooligan theme, so I added that:

rake theme:install git=""

I fixed a deprecation warning in _config.yml, changing pygments: true to highlighter: true.

The new method of using GitHub Pages locks the version of Jekyll through a Gemfile specified like so:

source ''
gem 'github-pages'

This is important, since they are using a fairly old version of Jekyll (1.5.1 versus 2.1.0) and a few other gems. From here, you install the github-pages gem which brings in the dependencies:

gem install bundler
bundle install

Following these steps will result in downloading the specific gem versions used for GitHub pages. This will make it a lot easier to figure out why pages fail to compile (email notifications are sent for these failures). In my case, it turns out that GitHub Pages was defaulting to using the maruku markdown interpreter, which is now end of life, and which was also failing to compile my markdown. The solution is to switch to the newer kramdown markdown interpreter by adding the following to _config.yml, noting that this field is not part of the latest JB configuration:

markdown: kramdown

Blog Post Development Workflow

The basic post development workflow looks like this:

 1 # start serving the site locally
 2 bundle exec jekyll serve
 4 # start a new post
 5 rake post title="Hello World"
 7 # write the post
 9 # rebuild the site
10 bundle exec jekyll build
12 # review post at http://localhost:4000

Typing jekyll build frequently becomes old fast, so I added guard-jekyll to the bundle and ran it like so:

bundle install guard-jekyll
bundle exec guard init jekyll
bundle exec guard

This will monitor the directory for file changes and automatically rebuild the site, so I can stay focused in Sublime Text and refresh the page in the browser.

blog comments powered by Disqus


28 June 2014