Sorry this page looks weird. It was automatically migrated from my old blog, which had a different layout and different CSS.

Mephisto Theme — AirBladey Style

Yay! I’ve just written my first Mephisto theme. Until now my blog looked completely different from the rest of my website. But now I have AirBladey — the theme that looks like, well, the main AirBlade site.

I’m writing up the experience in case anybody else is about to write a Mephisto theme. As Mephisto gets more popular I expect more people will try to customise its look. Here’s how.

Where Do You Begin?

Well you could start with a clean slate but it’s much easier to find a theme that looks roughly right. I chose the beautiful Hemingway thinking there’s only so much damage I could do to such high quality work.

I think modifying an existing theme was the right choice — but when I start work on AirBladey v0.2 I’ll start from scratch instead. I learned a lot from Hemingway but it has a lot that I don’t need.

What Is This Liquid Everywhere?

If you’ve written any Rails apps you’ll be familiar with ERB, the templating language used in the views. Those with authority issues might be using HAML instead. Whatever.

Either way you’ll be used to executing Ruby to do what you need to do.

Liquid is another templating engine. It was designed so that end users could safely edit the appearance of their application without bringing down the server. There’s no code so there’s no eval-ing so your users can’t do any damage.

Mephisto uses Liquid by default. There are plugins to replace Liquid with ERB, Erubis or HAML but I thought I’d have a go with Liquid. It’s the default so it must be good, surely? And how hard can a templating language be?

Not Feeling The Liquid Love

Maybe it’s just me. But as someone who is used to writing code that does stuff, it feels cumbersome using a templating language that is weak by design. In order to actually do anything, you have to pipe values into methods, er ‘drops’, into filters in an awkward, barse-ackwards manner.

Not only is the way of passing arguments unnatural, I found the terminology slippery too. Try googling for help on liquid filters or liquid drops; the few useful results are washed away by water purifiers and sewage treatment works.

I found this cheat sheet invaluable. But despite my best efforts I have to report that Liquid just didn’t click for me.

Here’s a prime example of the problem. I wanted to list my 3 most commented-on articles. All I needed was a simple sort on each article’s comments_count. Can Liquid do this? Not as far I can tell and I looked quite hard.

So I had to go to the trouble of writing a plugin just to make a single line of Ruby available to Liquid:

def popular_articles(section)
  section['articles'].sort {|x,y| y['comments_count'] <=> x['comments_count']}
end 

Unbelievable.

Since I’m the only one editing my blog’s appearance, the number one reason for using Liquid goes away. Next time I’m going straight back to ERB. Yes, yes, pipe down you crazy HAML people.

Some Templates More Equal Than Others

This useful overview of templates doesn’t mention that some are redundant. Hemingway ships with 8 templates, for example, and I couldn’t figure out the difference between index.liquid and home.liquid.

It turns out that templates are chosen by ‘mode’. Since the Home section is used for the front page of a ‘blog’ (as opposed to a ‘page’), home.liquid trumps index.liquid. Maybe the latter is used for ‘page’ sections.

Anyway, I’m not using page sections or tags so I removed page.liquid, index.liquid and tag.liquid.

Code Syntax Highlighting

After some CSS shenanigans I had AirBlog looking like AirBlade. Now I wanted to syntax-highlight the code snippets I post. There are two main options: CodeRay and CodeHighlighter.

CodeRay works out of the box. It produces fine-grained highlighting, which is good, so it’s important you can easily find out the many CSS classes that you need to write.

This is where it fell flat on its face. It produces hundreds of CSS classes with cryptic, non-semantic names like xs and t — and I just could not find any information on what the various classes meant. Or even a list of all the possible values.

Happily CodeHighlighter is much simpler. Written by unobtrusive Dan Webb, it works on the client-side to keep your markup clean. The parsing is less sophisticated, which would be bad in a text editor but is just fine for a blog article, meaning you only need a handful of CSS classes. And they all have sensible names like keywords. Thank goodness.

The only “feature” I’ve found with CodeHighlighter is that it increases the font-size of highlighted code in Safari. I’ll update this as and when I find a fix.

The Voice Of Reason

I like to see where the author of an article has commented on it because they often add interesting material not in the main article. I notice this all the time on Signal vs. Noise, 37signals' blog. In fact I read their articles then skim all the comments looking just for theirs. They make it really easy to pick out their comments and ignore the rifraf.

So I wanted to set up a special comment style for me. However it turns out you need revision 2625 or later, which is post 0.7.3. I’ll take care of it next time.

Move Along

I also like ‘previous’ and ‘next’ links to take me to the article before or after the one I’m on. These are available as “drop filters” but only in edge Mephisto. Another one for next time.

And The Rest

Other things on my list for AirBladey 0.2 are microformats (maybe) and better accessibility.

Conclusions

Mephisto’s theme management is excellent. You can completely change the look of your site just by choosing a new theme. For best results, though, you’ll want to write your own.

This is straightforward if you can drop Liquid (sorry, couldn’t resist). If you want syntax highlighting, Dan Webb’s CodeHighlighter is simple and works.

A few features like special comment styles and previous/next links are only available in edge Mephisto, but Rick Olson claims it’s stable.

Epilogue

Have you just written a Mephisto theme? Is there anything you wish you’d known before you started? Let me know in the comments.

Comments

Hey great article! very fun to read. quick question, while putting all the research together for this post, did you happen to come across any code highlighting options for something like ASP.NET?

shereen • 24 July 2008

Great post – I came across this while struggling with Liquid to write my own theme for Mephisto (I’m replacing my crusty old Wordpress site). I’m pretty handy with the popular web languages (Ruby/Rails, PHP, etc), but Liquid did nothing but piss me off. Weird syntax and so much effort just to get a piece of Ruby exposed to the templates. I finally gave up last night and downloaded the ERB plugin for Mephisto…but there isn’t a shred of documentation anywhere (as is typical of Mephisto). However, it didn’t take long to figure out some of the idiosyncrasies, and now my ERB templates are (so far) behaving correctly, and doing things that I couldn’t do with hours and hours of work in Liquid templates. Glad to see I’m not the only one not feeling the Liquid love! I really think they should have just made ERB standard and liquid an option…I bet that would have worked better for most people.

Thanks for the info about the code highlighting too! I’ll need that.

Matthew Rogers • 9 August 2008

Andrew Stewart • 17 May 2007 • Mephisto
You can reach me by email or on Twitter.