Marco Carag

Expert er of things.

I Love Jekyll and Github

I love Jekyll Bootstrap and GitHub as a blog platform — so much so that I’m sure I’ll write posts more often than once a year. Really. As a frontend developer and pixel-pusher, it might be the most pleasurable way to blog that I’ve tried yet. Not that I’ve tried much, but hear me out.

The Tools

A month after my last blog post in late 2010, I got a new job with a dating startup named HowAboutWe. It’s been an incredible and intense experience so far that — in addition to partly yanking me away from paying any attention to this blog — has introduced me to many things. Chief among those with regards to this post are Github for source control, Vim for code editing (and writing text in general), and Compass and Sass for writing CSS.

Wordpress theme components. Or…auto parts from Bangkok’s Chinatown.

I now have a flow at work that is a cinch to me. When the scales finally tipped, oh, maybe a year ago, and I set out to redesign this blog, it made sense to incorporate as much of this new beloved workflow as I could. It started with a new theme for my original Wordpress install. I worked on converting the stylesheets into *.scss partials for use with Compass. Vim was the editor, and I kept all my changes on Github. But it still didn’t sit completely right with me. Free time was short, and the once humble task of Wordpress theming and uploading via ftp to my web host felt intimidating.

Blogs are static beasts.

HowAboutWe used to have ad modules for third-party sites that would make complex queries to conjure seemingly timely and location-relevant content. In retrospect, this was silly for a couple of reasons — not the least of which being that trusting user-generated content for the purpose of advertising is extremely risky. (One that always brought smiles involved a user suggesting that he and his date join OkCupid rather than pay for our site.)

Instead, it made complete sense to curate the content, and just serve up quick and fast static HTML that would be browser cached practically to infinity. A day later, we replaced nearly all of these ads with the static content, and the elegance of the solution had big payoffs in both performance, and code maintenance. It was silly we didn’t do it that way from the start.

Keep it simple!

It wasn’t much of a leap to reach the same conclusions about blogs. I’d heard of static site generators like Jekyll before — years ago, in fact — but I never considered them useful for a blog. The thought of static HTML that I’d have to compile and upload after every post… It just sounded cumbersome. And then I realized that I wasn’t exactly producing a daily newspaper’s worth of content. Also, there are times when I’d want to do a good bit of custom layout for a given post. So, my post content would be peppered with HTML.

Writing HTML into Wordpress textareas always felt awkward to me. I would tend to hash out the layout in a text editor and separate HTML file before pasting it in to Wordpress.

Jekyll, and more specifically Jekyll Bootstrap, solve this problem. Jekyll works by pointing it to some template HTML, writing your content as either Markdown (*.md files) or HTML, and then running it. It mashes the content to the template and spits out a fully rendered website that you can then upload. And Jekyll Bootstrap adds some nice config setup, themes, and other great stuff that make blogging with Jekyll a near no-brainer.

So, using Jekyll, my posts are HTML files. And I could use Vim once again to author all of my content. When you install Jekyll Bootstrap (which installs Jekyll), it provides a server that you can run that will listen to a _posts folder for updates. The instant you save something in there, it does its template compilation, and your new content is instantly viewable at http://localhost:4000. Really awesome.


I’d learned a while back that people use Github Pages — basically, a Github repo that will automatically be served to — for blogging. I’d also learned, much more recently, that it supports Jekyll. Since I was already accustomed to source-controlling my work and some of my personal stuff with Github, deploying my blog simply by committing to a specific repo as normal sounded beyond perfect. Code, push, deploy became simply code and push.

I was concerned at first that I wouldn’t be able to push up drafts of posts without them being published automatically, until I had the “duh” realization that I could cut a branch ($ git checkout -b “2012-04-06-my-post.html”), write my post and push it in draft state to my hearts content. I could publish it when ready by merging the branch to master. Another fairly exact mirror of my normal workflow, and it feels great.

Github Pages is really what seals the deal with Jekyll. Ftp is out of my life now, and it’s bliss. Another important step was pointing my domain,, to Hopefully, your registrar gives you this capability, but it’s simply a matter of pointing an A record and a CNAME record to Github; the Github Pages Help instructions are pretty accurate in this regard.


I think it’s hard to overstate the awesomeness of removing the overhead of something as complex as Wordpress. I’ve been considering moving away from my current web host, but the idea of deciding on a new host, going through a new Wordpress install on that host, and putting my old blog data in its MySQL database almost makes me sick to my stomach.

The sites generated by Jekyll are not married whatsoever to any particular host and the services they provide. It doesn’t matter if my web host has a PHP server, .NET, Rails, or Node.js, or whether it uses MySQL, Postgres, or a document database. The end product is static HTML. If Github crashed and burned, I could upload that HTML anywhere else with hardly any setup needed.

And as awesome the admin areas of Wordpress are, in no way does its <textarea> compare to Vim in my view. I’m sure you’d feel the same with your text editor of choice. The short of it: If you’re a web developer intending to blog about code (or even not about code, if you’re as bad with Vim commands outside of Vim as I am), Jekyll and Github Pages is likely the best way to go about it.

Happy Blogging!
blog comments powered byDisqus