tools »

Getting Started: Jekyll

After years of successful procrastination, I accidentally a blog. Using Jekyll.

The blocker to blogging for me has always been finding the time to make the up front investment just to get down to writing. Efficiency is the art of eliminating work you don't have to do but, as great as some of the hosted blog solutions are, technical blogging still has a few niche requirements like code formatting which end up kinda hacky on a Tumblr or Blogger.

I had a web authoring project in an earlier epoch compromised due to a CMS vulnerability so a static site generator was a close second in terms of fewest moving parts. I didn't spend a lot of time shopping around for the tool to use, being a Rubyist I was well aware of Jekyll as a mature tool and since it's the blessed solution for GitHub Pages it killed a few birds with one stone.

It turned out not to be that simple, but what is?

Jekyll vs Jekyll-Bootstrap vs Octopress

At first glance, the appeal of Jekyll as a lightweight solution conflicted with my desire to minimize my time investment before I got to the writing but thankfully a lot of people have embraced the library and expanded on it.

After getting familiar with the core documentation, I had a look at Jekyll-Bootstrap. It adds in basic themes, configuration and some helpful integrations like Google Analytics and Disqus. There were a few things it didn't do, like create index pages for categories and tags, that I definitely wanted and a lot of the configuration points were complexities I didn't feel I'd need.

The other big contender is Octopress which adds a lot of great functionality and plugins out of the box that makes the end result feel very similar to a WordPress blog. Its gone to great lengths to have a highly responsive design but since its themes weren't based on Twitter Bootstrap it was going to take longer to achieve the kind layout I wanted.

In the end I decided to go back to baseline Jekyll, craft my own templates (with a lot of pointers from both of the above) and choose my own plugins for the essentials.

Plugins & Gotchas

The source is available on GitHub here if you're interested. The main things I've dropped in are:

Tag Cloud

There are a lot of snippets available to drop-in tag clouds, but the best implementation I found is here.

This gives you a clean and reusable class you can put in your plugin directory and then call in your templates.

Taxon Page Generator

The Jekyll documentation covers writing a Category page generator.

I ended up stripping down realjenius's version of this to write a Taxon generator that gave me paginated lists for both Tags and Categories.

GitHub Code Colourisation

The documentation covers installing and setting up Pygments for Jekyll, but I wasn't a huge fan of the default CSS.

Fortunately, aahan has a nice GitHub-flavoured stylesheet all ready for use with Jekyll here

Deploying

The main gotcha with Jekyll and GitHub Pages is that GitHub runs the site build with the --safe argument - meaning that all plugins are disabled.

Octopress has solved this.

The trick is to commit the Jekyll project to an orphaned source branch and then commit the HTML you build locally to master. I will probably pull together a rake task for making this a little smoother in future.

To Do

The main thing I punted on at this stage was putting in an asset pipeline to optimise CSS and Javascript files. I've also noticed the HTML that Liquid produces has a lot of whitespace that could be eliminated.

I'll probably pop in jekyll-asset-pipeline when I tinker with the source next and solve the HTML clean-up separately. I might look at a HAML preprocessor for my layouts, a quick test shows that it didn't choke on Liquid tags.

There are a few filters I might consider adding, things like shorthand tags for Twitter or GitHub handles / project names would be definite nice to haves but I'd need to consult the efficiency graph.

So... yeah.

Overall, I'm pleased with the resultant workflow and I have another project I'm considering using Jekyll for in lieu of a custom CMS.

I was fortunate to have Karen's help to make it look like something other than yet another Twitter Bootstrap site but after several evenings of tinkering it's time to ship and get writing.



blog comments powered by Disqus