Stephen Ramsay    Home

Back to the Roots Web with Jekyll

A few weeks ago, I wrote a post about how I had more-or-less stopped using graphical applications. In that post, I championed the command-line as a user interface that is superior, in many cases, to the ones to which we have grown accustomed. This, of course, was met with a storm of derision and ridicule. The mere mention of that post during THATCamp last week — THATCamp! — sent an entire table full of geeks at the Auld Shebeen into hysterics. Even some of the people who agree with me on the primacy of building in dh felt it may have been bad for the revolution. Everyone should build? Fine. Everyone should “code?” Okay, maybe. Everyone should use Bash? Well, that was a Forth Bridge too far for many.

Now normally I’d deal with this kind of public humiliation through a combination of childhood regression therapy and unfollowing people on Twitter. But one of the respondents to that post, Chad Black provided another outlet. “So, when do you ditch WordPress for something like Jekyll?”

And what, pray tell, is Jekyll?

Jekyll, my gui-besotten unfriends, is the best blogging platform I have ever seen. And the best way to run it, of course, is on the command line.

To understand what Jekyll is all about, it’s useful to understand a bit of the history of web application development.

Back in the mid-to-late nineties, most sites on the web were “static.” That is to say, most websites consisted of html files sitting on a file system. It’s not that there weren’t any dynamic elements to these websites. We had lots of cgi-scripts for generating dynamic things, and we had (an inconsistently implemented) Javascript. We would also build lots of filters and ad-hoc templating engines (often in Perl) for reducing redundancy. Our sites obviously weren’t as sophisticated as they are now, but they had one distinct advantage: the “website” was something you could poke around in by moving around the filesystem and looking at the various files. Static html in one directory, css in another, cgi scripts over there, etc.

Now, there were some problems with this. Good software engineering suggests that one shouldn’t mingle the content, the control/rendering logic, and the display layer of a software system. These different layers should, indeed, be so radically decoupled from one another that, ideally, you could pull one component out and replace it with another. This seemed very good to all of us who were growing up as web developers, because we were all learning Java at the same time. And Java was all about Good Engineering. At least, we thought it was at the time.

There was nothing about the static site that actively prevented SoC (Separation of Concerns) or mvc (Model-View-Controller) or the deployment of any other three-letter acronym, but it was easy to violate these principles, and beginners — which meant just about all of us — had a hard time getting it right.

Some time around the turn of the decade, it became absolutely de rigueur to move the content of your site off the filesystem and into a relational database. This was how serious websites were put together, and if you didn’t know what third normal form was, it meant you were an amateur.

Web development became — overnight — a much more complicated affair. In fact, that was precisely the moment when you could no longer put “html” on your resume and expect to be taken seriously. Website development was starting to become an engineering problem for engineers, and the much-vaunted Separation of Concerns began to be more fully extended to the team itself. Designers would now design, rdbms-ers would M, and middleware programmers would keep the whole thing glued together.

But just as, in a capitalist society, a market will emerge wherever value is assigned, so, in a technological society, a Framework will emerge wherever complexity develops. Before long, separating concerns became a complicated enough problem in itself that it required entire systems for managing it. We’ve been there ever since. If you’re building a Serious Website, you’re supposed to be doing it with Rails, or Django, or Cocoon, or Zope, or any one of dozens of Web Application Frameworks, some of which date back to this period.

It would be hard to lament any of this too strongly. Web development is a complicated affair these days because we want to do much more sophisticated things, and it’s hard to imagine doing it without some kind of framework. But even back when everyone (including me) was moving to databases on the back end, there was a small voice in the back of our heads — an embarrassing one, really, because what did we know? — that kept saying it over and over: This is too fucking complicated.

That voice is usually suppressed by the undeniable fact that you can throw one of these heavy-duty SoC-ed and mvc-ed websites together in minutes using any one of these frameworks. But the voice will return at some point, because (and I’m hardly first to note this) web application frameworks tend to make the standard case simple and the edge case damn near impossible.

The latter situation emerges, I think, because of what was lost so many years ago. You just can’t walk around your own website and figure out what is going on. For me, this is most frustrating with things like blogs. “Where are my posts?” I ask WordPress. “Here they are, sir!” is the reply. But where is that, exactly? I’m well able to move around a MySQL database, but the whole purpose of this framework — of any framework — is to make it so you don’t have to do that. And you don’t, until you have to. And then you find yourself in a terrible, horrible, no good, very bad place.

Tom Preston-Werner, the designer of Jekyll, describes it as follows:

Jekyll is a simple, blog aware, static site generator. It takes a template directory (representing the raw form of a website), runs it through Textile or Markdown and Liquid converters, and spits out a complete, static website suitable for serving with Apache or your favorite web server.

That almost makes it sound like the next big thing. In a rational universe, it would be (at least for some use cases). But actually, it’s a quite old thing. If there was such a thing as “roots web” (on analogy with “roots music”), this would be it.

Before I go any further, let me say that I think Wordpress is a fantastic piece of software (I am, after all, helping to develop a system that is entirely dependent on the Wordpress platform). “Jekyll vs. Wordpress” and “static vs. dynamic” bear all the marks of the beast in terms of potential for religious warfare, and I have no interest in this at all. But it is worthwhile noting what’s good about a system like Jekyll.

First, it brings us back to Total Information Awareness (if you don’t remember that term, you weren’t developing websites ten years ago). The content is in this directory, the stylesheets are in this one, images are over here, and so forth. If an image is broken or the styling is wonky, you don’t use the dashboard to find the tool menu (?) in the hopes that you can figure out which source to view. You go pretty much where you’d expect to find the problem.

Second, you can work in your own environment. Now, it’s true that my environment tends to resemble those used during the Carter administration, but it need not be this way. It is important, though, that you be able to use your own tools. I am a passionate believer in a piece of advice that I learned from the Pragmatic Programmers: “Use a Single Editor Well”

[M]ake sure your editor is configurable, extensible, and programmable. [. . .] If you use a single editor (or set of keybindings) across all text editing activities, you don’t have to stop and think to accomplish text manipulation; the necessary keystrokes will be a reflex. The editor will be an extension of your hand; the keys will sing as they slice their way through text and thought.

TinyMCE is a lovely little thing, but if I had to do everything with it, I would shoot myself immediately.

Another extremely useful thing about Jekyll is that everything is in plain text. This doesn’t sound like a big deal, but it’s one of the cornerstones of the unix philosophy and a damn good idea for just about any kind of data you actually care about.

Plain text is the only digital format that has persisted for decades without serious challenge. It runs on literally every computational platform in existence and can be munged into any other format that comes along. It can also be manipulated using more tools than any other kind of data. Vaunted claims are made for the ways in which things like xml facilitate long-term preservation and access, but nearly all of that benefit arises from the fact that it’s plain old text. Switch to text (which includes things like xml, LaTeX, and csv), and you’ll never again have the problem of migrating data from one spreadsheet, word processor, or data analysis system to another. You’ll also find it easier to backup, easier to put under version control, and easier to sync. I can open anything I’ve written since 1999 right now without the slightest bit of ceremony, and I can generate any other format that might be needed relatively quickly. That is not possible even with the most popular formats in common use.

Jekyll even takes that one step further by embracing Markdown as its markup language for posts. Markdown not only uses plain text, but uses the kind of highly intuitive markup system that people tend to invent spontaneously when writing things in a plain-text editor. With the right tools, you can translate the Markdown texts into html, LaTeX, or pdf. More importantly, you can do that even if you don’t have such tools (which will be the case for your data some years hence when platforms and formats that have yet to be conceived will suddenly exist).

The greatest thing about Jekyll, though, is that it makes things only as complicated as they need to be. It used to be said of Perl that it makes easy things easy and hard things possible. It don’t know if that was really true of Perl, but it’s certainly true of Jekyll. It’s just enough scaffolding to prevent website development from becoming a tedious chore, but not so much that the implementation of some genuinely complicated feature requires comprehensive understanding of the deep recesses of the platform.

Needless to say, I’ve migrated my entire blog from WordPress to Jekyll, including all comments (now hosted on Disqus). In fact, this site does everything the old one did, and also functions as a more traditional home page (a thing that I always found irritatingly difficult with WordPress).

Right now, Jekyll and its relatives are geek territory, but soon I think we’ll start to see “out-of-the box” versions of static site generators that make it “trivially easy for anyone to generate a complex website” using a brilliantly architected framework. If you’re a web developer, my advice would be to enjoy the moment before the cycle begins again.

blog comments powered by Disqus