It’s time for something new

After 14 years we’re hanging up our keyboards. Our team is joining the lovely people at Culture Amp, where we’ll be helping build a better world of work.


Introducing TumblrThemr

By Max Wheeler24 Mar 2011

Let’s face it, creating themes for Tumblr sucks. While the theme engine itself is great, no matter how you tackle it, developing a theme involves a time-consuming mess of manual copying and pasting, saving, testing, and copying and pasting again. I’ve wanted to make a couple of themes since my first foray into Tumblr theming (way back in 2008), but given up each time knowing I was in for a frustrating development process.

TumblrThemr screenshot

To that end, we’ve just put the finishing touches on our latest pet project: TumblrThemr, a nifty tool that helps with Tumblr theme development. Built in collaboration with the talented Jim Whimpey, TumblrThemr lets you develop and navigate your themes locally using real data from your Tumblr blog.

How it works

  1. You install our special XML Tumblr theme on your Tumblr blog. This outputs your blog’s data into machine-friendly XML.
  2. We have a web service which converts and escapes that XML into a JSON data source for client-side templating.
  3. We interpret your custom .tumblr file and render it using your data.
  4. Then we hijack your theme’s links to reload different pages locally.
  5. Voila, local Tumblr theme development!

It’s not a complete replacement for the Tumblr engine — there are some limitations to the the approach we’ve taken — but it does make Tumblr theming fun again. I used it to build the theme for the RentMonkey blog from scratch and it was dead simple, almost identical to my normal development process.

For the technically minded, here’s a bit more about what’s going on behind the scenes.


We’re using Yehuda Katz’s excellent Handlebars.js (an evolution of Moustache.js) for templating. Out of the box, Handlebars.js uses double or triple curly brackets {{variable}} to identify variables for output and a different syntax for block helpers, so we’ve modified it to interpret variables and blocks using Tumblr’s single bracket and {block:Variable} syntax.

Handlebars.js basically maps a JSON object to the structure of our template, so we needed a way of turning Tumblr data into JSON. We didn’t want to use the Tumblr API because it doesn’t map to Tumblr’s theme engine and so would have meant making the app replicate the functions of the engine: complex and messy. This is where our XML theme + Sinatra app comes in. The XML theme is constructed so it outputs (as best as possible) the correct data from Tumblr based on the URL request, in essence we’re using the Tumblr theme engine to replicate itself. The Sinatra app is just there to get around some of the quirks of the theme engine and ensure we get nice clean JSON to play with. The Sinatra app is running on Heroku and if you’re interested in that code it’s up on Github.


Local requests are handled by Sammy.js, a weeny framework that’s kind of like Sinatra for JavaScript. Sammy.js lets us keep the state of the app — source URL and the name of the theme file — by routing everything through the URL hash, meaning you can edit, save and refresh to your heart’s content! It also means that for hijacking the internal links we can simply push them into the URL hash and sammy.js will do the right thing.

Link hijacking

Nothing special going on here. Just a little help from jQuery and a regular expression or two to ensure that we’re grabbing any local links — absolute, relative or file:// — and passing the request onto Sammy.

That’s about it! No more excuses, head to TumblrThemr, download a copy of the app and get theming!