Octopress

Sun 09 March 2014

Filed under Static Site Generators

Tags Octopress

I had high hopes for Octopress, because it's really cool, and it's easy to set up, and it's easy to use. It's really impressive how accessible it is. But as I later discovered, that ease of use doesn't mean much if it's too hard to diagnose problems resulting from updates to Octopress and/or Jekyll. So, I have to abandon Octopress unless/until I'm knowledgeable enough to troubleshoot it.

You know, I hadn’t originally intended to include static site generators in my recent Markdown experimentation. Some time back, I went on a pretty aggressive search for static site generators that were user friendly enough to be easy for someone like me (whose relationship to the command line is uneasy at best) to use. My conclusion? static site generators are no-man’s-land for non-technical users.

I don’t think I was really wrong about that. And it’s too bad, because I think the pool of folks who would benefit from static site tools is much broader than their current audience. L33t hax0rs aren’t the only ones fed up with Wordpress, Tumblr, etc. And while there are interesting minimalist Markdown-centric blogging tools in the offing that are more accessible, there’s a lot of not-ready-for-prime-time going on in that space. Everything’s in beta, and quite a few get canned before they go anywhere interesting. In the long run, I have high hopes for Ghost and for at least one of the Scriptogram family of quasi-static blogging tools, but in the immediate term, it doesn’t seem like any of those tools is really ready.

So, I had pretty much resolved myself to sticking with Wordpress and a markdown plugin for now. Then, yesterday or the day before, I came across a mention of Octopress while researching something related to Pandoc. As I followed down the inevitable rabbithole, it seemed like Octopress was actually not all that hard to set up and start using. So…I did.

Thoughts so far:

Setup

Octopress really is very easy to set up. Well, for certain values of easy. It’s not foolproof, certainly, and it’s really not ready for non-technical users as such. They helpfully disclaim:

Octopress is a blogging framework for hackers. You should be comfortable running shell commands and familiar with the basics of Git. If that sounds daunting, Octopress probably isn’t for you.

But, that being said, the installation process is well-documented, and I found that following the steps as they were laid out, I was able to get it set up fairly quickly.[1] And once it’s set up, there are quite simple commands to create new posts and pages, preview locally, and generate and publish your site.

Git

The main hangup for me was Git. I have basically zero Git experience, and frankly I find it pretty surreal. (I think the issue is that the actions you’re taking in Git have a somewhat abstract relationship to the normal user experience of the file system.)

There are great resources for learning Git, and a lot of things I love and use live on Github. So I really shouldn’t be as unfamiliar and uncomfortable as I am. But here we are.

Octopress’s documentation does, again, lay out all the steps you need to get set up. I even found it relatively painless to host on Github Pages[2]. And once you are set up, it doesn’t seem like you need to interact directly with the Git stuff in day-to-day use. Although it’s probably advisable to try to have a handle on what’s going on behind the scenes. : )

Themes

There’s a decent selection of Themes available. I haven’t experimented extensively – I just found one I liked, and installed it using the directions provided.

Using Pandoc with Octopress

I’ve gotten pretty accustomed to doing as many things as I can using MMD and Pandoc. I mean, pandoc -f markdown_mmd just rolls so trippingly off the tongue, right?

Pandoc isn’t one of the default options, but in fact the whole reason I’d gotten onto this Octopress kick was because I was researching Pandoc and came across a reference to using Pandoc as your Markdown processor in Octopress.

That’s actually overkill (I guess since I don’t do math), but with some additional googling, I was able to figure out something functional without too much difficulty. Just put a pandoc.rb file in the plugins directory, and modify your config.yml file like so:

markdown: pandoc  
pandoc:  
    flags: '-markdown_mmd --smart'

or with whatever options you prefer.

Of course, this isn’t really necessary for most users. The normal processors available in Octopress will do Markdown Extra, as far as I can tell, and for blogging purposes, that should be fine for almost all one’s formatting needs. But this way I don’t have to keep track of more than one syntax and processor.

---