Aseem Kishore

The making of

I started this blog over a year ago. I promised to share my thoughts and ideas here, but that’s barely happened! Time to change that, and what better way to begin than to share the code behind this blog itself?

Context

Your first question may be, why is there any code at all? There are plenty of feature-rich blogging sites and services out there, and indeed, for most people, I’d unequivocally recommend using one of them. (I’d personally recommend Tumblr today.)

It’s a fair question, and I don’t have a great answer, but Marco Arment sums it up nicely:

I’m a developer. I make things…

This probably won’t sound sensible to non-developers. But it’s very important to me to have that level of control over my site.

With that out of the way, the next question was: How? What language, framework, tools?

There were three main factors I cared most about (and still care about) when making this decision (not necessarily in this order):

  1. Development - it should be easy and fast to develop.
  2. Deployment - it should be easy and safe to deploy.
  3. Cost - it should, ideally, be free!

What you see today is the result of these factors. Let’s dive right in…

Act One

With hosted services out of the way, using something like Jekyll to develop with was a no-brainer. No database to manage and worry about, posts as just regular files, and support for Markdown; what wasn’t to love? (Tom Preston-Werner has a great post about the rationale behind Jekyll.)

Despite that, I didn’t like the idea of using Jekyll to power my entire site. Call me old-fashioned, but it just felt “wrong” to have to regenerate every single page when only the footer changed.

So using some sort of server-side scripting/templating language felt “right”, but at the same time (ease of development), I didn’t want to have to launch a server when developing locally.

I thus settled on using PHP with Apache: available by default on Mac OS X, always “running”, no build/compile step, and despite both their flaws, they’re both straightforward and simple to use for a case like this.

Part of the motivation for that was also that my domain, purchased from GoDaddy, came with free PHP hosting. (I’m not linking to GoDaddy for good reasons — I’ve happily moved to Hover.) I just had to use FTP for deploying, which wasn’t a big deal as I used Coda at the time.

Unfortunately, Jekyll didn’t play completely nicely with PHP, and the result meant a build step (a small one, but a build step nonetheless). Despite that, I went with it, and this Jekyll+PHP mashup worked for a while.

You can browse the code from this period if you’re interested.

Act Two

But pain showed up when I revisited this blog nearly a year later. In particular, FTP felt cumbersome and silly (I had moved from Coda to TextMate). Deployment was neither easy nor reliably safe.

It made sense now to move to git for deployment, just like I was already doing with “real” websites. Setting up my own git server felt like overkill to me, so it was time to move to an app platform in The Cloud™.

I was already familiar with Heroku, but Heroku doesn’t support “naked” domains (no www), and for a static site, it’s also expensive ($35/mo.), unless you’re willing to put up with long load times.

But I also knew that a potential alternative was GitHub Pages. After all, it’s specifically meant for hosting (only) static content, and it specifically supports (only) Jekyll for generating that content.

And unlike Heroku, GitHub Pages is free and fast, and it supports naked domains! (This isn’t documented clearly for project pages, but you just add an A record like you would for user/org pages.)

Unfortunately, GitHub Pages has two limitations: it only supports Jekyll — so no PHP or similar — and it even locks Jekyll down to disallow custom plugins — so no helper extras like LESS or SASS.

Fortunately, Jekyll does include support for a templating language called Liquid, built by Shopify. Liquid lacks the flexibility and expressiveness of “regular” languages, but it’s safe and secure for hosts like GitHub.

I was reluctant to switch to a completely new and less popular templating language, but the benefits of GitHub Pages outweighed these costs to me, so I decided to bite the bullet and port my site.

And indeed, the result is what you see today. You can browse this code too if you’re interested.

Details

Porting this site to Jekyll and Liquid for hosting on GitHub Pages wasn’t trivial — it was in fact filled with gotchas. And issues remain.

Liquid, for example, doesn’t seem to have a notion of (user-declared) array literals. That would have been useful in cases like the nav bar, e.g. to iterate over a list of links like ['About', 'Blog', ...].

GitHub Pages also uses an outdated version of Liquid, since updates to Jekyll are sitting unreleased, so newer Liquid features like index_of() and join() are also unavailable for use.

GitHub Pages also caches very aggressively — too aggressively for regularly updated sites like blogs. I’m not the first one to notice, and I’ve tried to come up with workarounds, but none have worked.

It’s not all bad, though. In fact, GitHub Pages has some great features that were delightful to discover.

Most useful is that it has simple support for clean URLs baked right in: a file at /foo.html can also be accessed at /foo (no trailing slash), as long as no folder /foo/ exists. This site takes advantage of that.

I’ve also been impressed by the thoroughness and thought that’s gone into GitHub Pages. MIME types, HTTP headers, even details like making sure HTML5 cache manifest files are never cached — good stuff.

Review

Overall, I’m quite happy with this new setup. Liquid is workable, Jekyll is great, and GitHub Pages is a pleasure to use overall.

If I had a wishlist for improvements I would love to see, it’d be something like this (in rough priority order):

  1. Eased caching on GitHub Pages. Browsers could still cache pages; they’d just check first, and GitHub would respond with a 304 Not Modified.

  2. Support for Jekyll plugins on GitHub Pages. This is understandably a security concern, but maybe the most popular plugins could be vetted and supported, just like Pygments is for syntax highlighting.

  3. Support for another templating language in Jekyll. Liquid is great for non-technical uses, but it’s just so verbose and cumbersome for general-purpose templating. This could maybe be solved by a plugin.

  4. If not, streamlined syntax in Liquid. Shorthand tags and operators would be a great start; variable assignment could also use improvement.

Still, the current situation is pretty fantastic: write posts in Markdown, deploy via git, and on a host that’s both fast and free. You can’t ask for much closer to “ideal” here.

Alternatives

But we all strive towards different “ideals”, and two alternatives are worth mentioning here.

The first is Octopress. This is a WordPress-level project that builds on top of Jekyll, and it’s simply impressive. In fact, this is strongly worth considering if you’re looking to start (or revamp) your own blog.

The second is Joe Hewitt’s Dropbox-based setup. The code behind the actual blogging platform is custom, and it requires server hosting, but you have to admire the nirvana of simply saving to publish.

I’m not aware of any other great alternatives, but let me know if you have any other recommendations worth checking out.

Onward

This site and blog have been an ongoing pet project, but after some effort, I’m quite happy with the current setup and workflow.

I’m also happy to finish this post and use it to kick off more regular sharing here! (Although just this post took me over a month of on-and-off writing, so don’t expect updates too frequently…)

With that, time to finally save, commit, and push. See you next time!