Nanoc Is Now My Blogging Software

So if you look at the archives, it’s been a while since I blogged. Quite a while. Okay, fine, a long while. I have been writing blog articles for the past year, but I don’t see to finish them.

And I’m going to blame my tools.¹

Frustration with my tools

I had been using Jekyll and Octopress. Octopress originally impressed me, even though version 2.0 was a git repository that I had to fork. Updating Octopress meant pulling from the original repo while I kept my own content in my fork. That was fun. Fortunately, version 3.0 moved to Ruby gems, and so updates were just normal bundle pain. It was quite happy with Octopress 3.0.

But then Jekyll 3.0 came out. I tried upgrading my site a few times, but Octopress 3.0 does not play well with Jekyll 3.0 at all. While there is some activity on the Octopress repos, the last release was last July. I’d hope it’d at least keep up-to-date with Jekyll, but I was also looking forward to some of the new (promised) features.

I also had a problem generating my site with jekyll server; this recompiles the site on a change to any file. I’d expect this to take just a few seconds, especially for my rather small site. However, I’d make a small change, and Jekyll would recompile and recompile and recompile and… For minutes. When I’d kill the server and restart it, Jekyll would process the site in just a couple of seconds. Perhaps, this is fixed in Jekyll 3.0, but I could find out if I stuck with Octopress.

And that’s when I started wandering the Web.

Greener pastures

I did a search a year ago for static-site generators. Octopress 3.0 looked really promising. Middleman was tempting for another website I wanted to put togther, but it didn’t seem to work well for blogging.

But it’s been a full year since I did this search. I’m way overdue for a new technology.

My search this year yielded Nanoc. It must have popped up last year, too, but I forget why I rejected it. I read through the tutorial and some of the manual, and I was intrigued, bordering on hooked.

Jekyll and Octopress has blogging built in, very prominently (and somewhat rigidly). Nanoc appealed to me because I saw the building blocks I needed to put my blog together. It has plenty of helpers for blogging, but it’s not prescriptive how you have to use them. And what few abstractions it had were pretty good.

I had thought that the built-in blogging had drawn me to Jekyll and Octopress, but now I think it was the built-in HTML and CSS layouts and themes that appealed to me. And those ended up frustrating me because they didn’t quite do what I wanted, I wasn’t sure how fit together, and they used a templating language unfamiliar to me. Nanoc seemed to do what I wanted it to do, I understood how things fit together, and Nanoc supports ERB out of the box.

So I’d have to come up with my own layout and design (not a trivial task for a design-challenged engineer like me), but I figured I could crib something together using Bootstrap. Everything else I could do on my own if I couldn’t find a solution in Nanoc or in another gem or in a blog post.

Goodbye, Octopress, hello, Nanoc

After reading through the Nanoc documentation, I pretty much had my mind made up to switch to Nanoc, unless something went really wrong. I created a Nanoc site, and then just worked my way through the manual pulling in whatever bits and pieces I figured I needed for my site.

It’s taken a couple of hours. I had some frustrations getting the right Markdown parser (answer: kramdown) and most importantly the right syntax highlighter (answer: rouge). I’ve had to fight with CSS, but mostly that hasn’t been too bad. It was really easy convering my old blog posts for Nanoc.

I like what I got.

Some things I really like:

• Content goes in the content directory, layouts in layouts, output in output. The structure is up to me within those directories.²
• guard-nanoc does a great job rebuilding the site. One pass and the whole site is built quickly.
• Nanoc uses checksums (and maybe timestamps) to write only the output that really needs to be written. It removes output files that are no longer being generated.
• I understand the code and configuration much better.
  • I got support for tagging done in about an hour, including a tags page listing all tags and their articles. I also pick an image for the blog post based on the first tag listed for the article in the frontmatter.
  • I got an Atom feed done in less than an hour using Nanoc’s built-in helpers.
• I’ve confirmed that it’s the layout I want someone else to do. Bootstrap isn’t too bad.
• Nanoc’s documentation is quite good. I found a lot of good blog posts, too. Some that stand out:
  • “The Quest for the One True Static Site Generator” by Jan Van Ryswyck.³
  • “Building a static blog with nanoc”by Dave Clark⁴

So I’m super happy that Jekyll and Octopress exist, and I wish them the best, but they just aren’t the tools for me. Maybe another year from now I’ll be bitter about Nanoc, but for now I have an okay website with a technology I understand a bit better.

Footnotes

blogging rant