A while back, I heard about this thing called Jekyll. Apparently, it was a "blog-aware static-site generator," was open-source, and had something to do with Ruby, blogging, Github, and Tom Preston-Werner. Programmers seemed to like it (many mentions on Hacker News), so I figured, since I'd managed, with so much effort and so many times over the years, neither to find nor create a satisfying blog platform of my own, that I should maybe sit down and give it a try.
My biggest gripe — well, I have two of them. (Actually I have dozens of gripes, but I digress.) As a non-programming person who wants to set up a blog, your only real option is to use one of the many hosted services: your Bloggers, your Wordpresses, your Tumblrs, etc. My wife's been paying for TypePad for years, and has a lovely (if much too rarely updated) blog, but every time she sits down to craft a post, it's rage against the machine: the WYSIWYG editor is crap, won't put her pictures where she wants them, things start wrapping all stupidly, or the links all break — it's always something, and I usually have to jump in and fix things at some point, if only to bring her blood pressure back down to normal human levels. Ultimately it works, so we stay with it, but I'd be lying if I said we didn't hand over our eight bucks every month without at least some grudging gnashing of teeth. At least for my part, because as a programmer, I know it should be lot easier than it is.
If you do know something about programming (even if it's only a little HTML), you might not realize you can actually craft everything yourself; even the faciest of platforms has only one job, and that's to deliver HTML to a browser. If you can write this much HTML:
<h2>Good Morning, Readers!</h2>s
<h3>October 8, 2012</h3>
<p>A funny thing happened to me on the way to work this morning...</p>
... then you can build and manage your own blog. It doesn't take much. Just about anyone can learn enough HTML in an afternoon to build a basic blog.
But then of course, once you know a bit of programming, you tend to want to know more, and everyone eventually wants at least something they've seen somewhere else on the Web: you want to upload pictures from your phone, you want to set up comments, you want tagging, you want RSS, take your pick. Basic HTML certainly works, but only gets you so far.
Since I'm a programmer, I've generally opted to roll my own. I started ten years ago with Classic ASP and an Access database, graduated to C# and SQL Express, and eventually settled on ColdFusion, also with SQL Express (and don't laugh, by the way — CF is definitely weird, but incredibly flexible and productive). But the pain of building and managing a homegrown, relatively feature-rich content-management/publishing system just got to be too much for me. When I was 25, I had all the time in the world to muse on database schemas and to craft obscure, intricate features (however cool I might've thought they were at the time), but today, with three kids and a career, free time is scarcer than diamonds. If I'm lucky, I can steal an hour or so in the morning to write. But rarely more. And I'm usually not that lucky.
All this is to say that my relationship with blogging over the years has been of the on-again, off-again variety — mostly off-again, because I feel about blogging the way I feel about coffee: it shouldn't be that hard. Coffee is ground-up, roasted beans with hot water filtered through them; you don't need a $3,000 machine to make it. (Although feel free to click that affiliate link if you disagree.) That's why I love my Chemex: it acknowledges that essential simplicity, and gives you suitable (and suitably priced) tool for the job.

So when I heard about Jekyll, and how it seemed to have grown out of that same minimalist ethos, I was interested.
Unfortunately (at least for me), Jekyll's how-to documentation is split into two general categories:
The official documentation, which is nicely contained in the Jekyll wiki but not nearly complete enough to get started from square one, and
Spread all over the freaking Internet, mostly on random programmers' Jekyll-based blogs in the form of very specific, sparsely described code snippets that end up raising more questions than they answer.
After that initial dive-in, and an investment of several hours, I still had one rather problematic question: How does this goddamn thing work?
Yes, I understood all of the words in the documentation, and yes, I realized all I had to do was run jekyll and some sort of magic happened and out popped a simple, static Web site, which sounded awesome. And I could see all the configuration options and Liquid template extensions, yes. All that looked great. But where did the configuration file go? Did I have to create one myself, or was there some default I could get started with? What, exactly, is Liquid? And I see this stuff about categories, but what about tagging? I had no idea how to get started, so with time as scarce as it was, I set it down, hoped to come back to it, didn't, and then lost interest. At one point, I discovered Octopress, which is based on Jekyll and which seemed rather nice, but which I discovered after another investment of time also suffered from inadequate documentation, ironic complexity, and lots of bugs, so with yet another wistful sigh, I git rmed that project, too, and hoped to come back to the whole thing again for another try someday.
Which, after some time away, I did. And somehow, through the magic of random Web browsing coupled with pure experimentation and trial-and-error (including the reading of many error messages), I came to realize that the answer to that one, basic question I'd had was simply this:
Jekyll is a Ruby script that, when you run it, reads every file of your site and pulls it all into one big Ruby object called site. If a file contains some special YAML at the top of it, Jekyll will use that YAML to stick some properties onto the site object for you (e.g., some tags, a date, an arbitrary Ruby object of your own creation, whatever you like). Then, once all the files have been read and the site object created, Jekyll will render the site object in a directory called _site by looping through all of your posts (which you put into a folder called _posts) using the HTML templates and Liquid expressions you provide. If you'd like Jekyll to do something more than just that, you can create a Jekyll plugin by writing a little Ruby code and putting it into the _plugins folder.
That's it. That's all I needed to know, but for some reason, nobody explains it that way. Jekyll builds one big Ruby object and then spits it back out as static HTML. Finally, it made sense. And I was off and running — and this blog is the result.
So, a couple of things to take away from this experience:
Somebody needs to write a book on Jekyll. I've decided that person might as well be me, so I've started writing it and am well on my way. You can follow the progress of my Jekyll book on LeanPub.
Plugins are really easy to write, provided you know the magic words. I've written and open-sourced a few plugins of my own already that I also use on this site: one for embedding Flickr photos, one for SoundCloud sounds and a couple of others for working with video clips.
Jekyll is, at its core, so simple that even non-programmers can learn to use it with a teeny bit of effort. This is one of the major goals of the book, too — helping aspiring, technically inclined bloggers use Jekyll and other open-source goodies to seize the means of production, as it were.
Jekyll is the publishing tool I wish I'd had in 2001. I hope to be able to help a lot more people start using it.