OakTree, the Blog Tool Thing

Sometime after the new year, I began work on a small project to replace WordPress with my own blogging tool. The goal was to meet all of my needs and absolutely nothing more. The product of this work is OakTree, so named for the WordPress theme I designed for Spifftastic. Aside from that one mention, OakTree in this post refers to the OakTree gem and blogging tool thingamajig. So, let’s run down a few points that I’d like to ramble about, because OakTree is eventually replacing WordPress on this site.

This post is fairly out of date. Spifftastic now uses Hugo. You can see the last section of this post for the general reason behind that decision.

What Is OakTree?

I cover this in the README for OakTree, but it is essentially a tool to generate a static HTML blog. It takes in a series of posts and spits out the blog. It is very simple to use, seeing as there are a grand total of four commands you use to interact with the blog via the oak tool: init, newpost, sync, and rebuild. The last two are the same thing with a minor difference, so it’s actually much closer to three commands.

An OakTree blog is comprised of two things: templates and posts. Posts are stored in a source/ directory, templates in a templates/ directory under the blog’s root, and the generated content under public/. Posts are Markdown files with a bit of metadata at the top to store a post’s title and time (in case you want to, say, publish something with a future date). Templates are written using the wonderful Mustache, so it’s very simple and very easy to get things working.

To start a blog you run oak init in some folder or other and your blog is generated. This produces a blog_spec file with some data about the blog you’ll need to customize, as well as source/, public/, and template/ directories. The template directory comes with a basic blog.mustache template file that you can then customize to whatever ends you like. It’s actually not that bad of a starting template if you like barebones sites. After that, you create some posts and run oak sync (or oak rebuild, if you’ve modified templates or something looks off, to regenerate the entire site).

Like I said above, this is simple. OakTree is not trying to do everything, it’s just trying to do what I want in a way that’s easy for me to use. It’s slightly git-ish, though far less sophisticated and probably nowhere near as fast. The important thing to remember is that OakTree is made specifically to do one thing: generate a blog. It doesn’t run a preview server, it doesn’t monitor your filesystem, and it doesn’t do much of anything sophisticated. It’s dumb and predictable and I like it that way.

One minor note: OakTree is a Ruby gem. It is written entirely in Ruby because that seemed like the easiest way to get things running. Turns out I was right, Ruby is the easiest way to get things running. I don’t really want to focus on how OakTree is implemented or what language it uses because it doesn’t matter and nobody gives a shit. It might be important to anyone who attempts to use it for their own site and decides they want, say, post categories. They’ll have to dig through the Ruby and prod me with questions to do that, but it’s really not important.

What’s Wrong with WordPress?

Though there’s nothing particularly wrong with WordPress, it tends to lean on the overkill side of things. WordPress tries to be everything to everyone, it is the universal blogging tool of blogging tools. This is nice and it shows a great deal of care on Automattic’s part, but this also means I’m stuck customizing a tool to fit my needs.

Take link posts for an example of a feature not built into WordPress – these are currently a hack sitting on top of the OakTree theme and rely on custom fields in posts. Just getting them working was a pain in the neck, and they’re still not quite right. OakTree does them exactly how I need them, and doesn’t require using filter/action hooks to make things work.

After that, we have databases and gigantic amounts of code that I know nothing about. How long would it take to familiarize myself with WordPress’s source code? Probably longer than I care to spend. Additionally, working with a database means I have to keep backups of two separate parts of my site, and having done this a couple times already (switching hosts and whatnot), I know I don’t want to deal with restoring from a backup again. It’s not very fun. Overall, it just means there’s more I have to concern myself with, and I would much rather not think about how my site works (strange as that sounds).

OakTree as a result is static HTML. There’s no database, no admin page, no configuration files on the server, nothing other than site content. It’s very convenient. It’s not particularly clean, considering it makes a mess of the filesystem, but the way the resulting blog is structured works well enough that it’s not terrifying either. I imagine it’s very rsync-friendly.

What’s Wrong with <Other Tool>?

I looked at a few other tools before starting this. One was Octopress, which I believe I heard about by way of Matt Gemmell. It’s a pretty nice system, and I’d recommend folks check it out just because it’s quite neat. Problem is that it’s also very large, and I don’t quite know what’s going on in it, and customizing it looked like it was going to be more trouble than it’s worth. So I’m not using Octopress. I had a hard enough time installing it in the first place, so I just don’t want to work with something that I don’t fully understand. Further, Octopress uses Jekyll which in turn uses Liquid. Liquid is not fun. I’d much rather have a mustache than diarrhea, however that goes. That’s not an objective opinion, by the way – I just plain don’t like Liquid.

Movable Type is another nice tool1 that’s far too large and menacing for me to wrap my head around. It seems to require a database, but may not use it to provide content — just for working on the blog, so that’s a plus. It’s a nice trade-off. That said, it didn’t get rid of the database, so I’m not entirely comfortable using it. I’ll also reiterate the “far too large” comment: Movable Type is an old (sort of) tool, and that usually means there’s a lot under the hood. I’m not interested in figuring out how to work with it (which is obviously a failing on my part), so it’s off the list.

There are probably some other tools out there I looked at but dismissed just because they disagreed with me in some way or other. Overall, my needs were so simple that it made more sense to just write a quick tool to do this myself.

Does Spifftastic Use OakTree?

As of December 20th, 2015, Spifftastic now uses Hugo. This is largely because I don’t want to continue maintaining OakTree, but also that Hugo allows me to focus less on fixing things in OakTree when they go awry (and they often do, since the version I use is a private fork of my own code just so I don’t have to share certain things).

Besides that, OakTree’s obviously written in Ruby. Much as I love Ruby, this makes it that much harder for me to jump back into working on OakTree. It was the first gem I wrote, and it is undoubtedly poorly written. It was great for doing a bunch of string processing, and Kramdown remains my favorite dialect of Markdown, but maintaining that code is awful. Hugo, on the other hand, is written in Go, and after I’d made Go one of our primary languages at Kochava, I have a better appreciation for how easy it is to just dig around Go source code and figure out how it works. Besides that, it’s faster to work with. No fault of Ruby, in this case, just an issue with old code.

Yes, it does. As of August 9th, 2012, Spifftastic uses OakTree for rendering. Prior to this, the transition was mostly on hold while I took care of greater priorities, especially my education. Once free time came around, I went back to finishing off the few remaining points needed to move Spifftastic to OakTree: RSS feed generation, static pages, and increased stability. RSS feeds were my main concern, as they provide the main window into blogs for many users. Static pages could have been kludged, but were easily implemented thanks to the way OakTree handles blog modes, so to speak.

Prior to this, OakTree has been used for a couple other projects of mine. This includes .nil?, my GitHub personal page. It did, at one point, generate Spifftastic (as the striked out text above says), but no longer does.

Ha, no, of course not. See, there’s a problem: I have to move everything from the database to source files. In addition, I have to convert my WordPress theme over to OakTree (this is the best way I can think to word this other than “I have to port OakTree to OakTree”). OakTree isn’t finished either – it still needs support for RSS feed generation (which I imagine is fairly simple compared to the rest of the project). The process of moving Spifftastic from WordPress to OakTree will be very slow, but it’s inevitable.

  1. I call all these things tools because I view them as just that: tools. They’re things that should help me accomplish something. Others view them as blogging platforms or what have you, which seems a bit like overkill to me. Sometimes all you need is a hammer, not a pneumatic nail-pounder. I don’t know if a pneumatic nail-pounder exists, but it sounds cool. Might just be a fancy way of saying “nail gun.” [return]