Blogging with Clojure and Markdown

July 8, 2017

There is an overabundance of blogging engines which are great if you need all the configuration, but a terrible distraction if you don't. I needed to put down some coding related notes and experiments somewhere, and the idea of writing in markdown and converting it to static HTML instantly appealed. No distractions, any hosting will do... but what do I use for converting?

Clojure, of course. Or more specifically, Cryogen.

The first thing I noticed was that the project page uses a font I like - the kind that makes you think of old books - and this is how they bought me. Let me tell you, then, a bit more about what it feels like to use Cryogen. This is going to be more of a review rather than a blow by blow install tutorial, because tutorials have already been comprehensively covered.

Looking good

So I grabbed the install, ran lein ring server and marvelled at the docs and default posts immediately popping up in my browser. And because this was to be a distraction- and procrastination-free blogging experience, I instantly decided to mess with themes and personalise the page a bit instead of, y'know, actually writing something. As you do.

There are only three themes available for Cryogen out of the box. Wordpress it isn't. At first, I decided to add and install Lotus. I got a face full of warnings, discovered I needed to install sass and compass, okay, and... I couldn't get the resources to work properly.

But since, y'know, distraction-free blogging experience... I decided to do something of my own. Luckily, it's not very hard to roll out your own theme if you base it on the existing code. What you're seeing now is the basic blue_centered theme, highly modified with inspiration from Swiss Jekyll theme. All in all, painless.

Cryogen templates use a templating system called Selmer. If you've ever used templates, the format will be instantly familiar: {{thing|filter:argument}} with a decent amount of already implemented filters.

I played around with date formatting (grumbling about "those Americans" that encode month-day-year everywhere as default) and discovered that date formatting is based on Java which does not provide an ordinal suffix for the day of the month. You know, for when you want to sound proper old school and write "Monday, 23rd of April 1892". Let us pause for a moment of nostalgia for PHP's date()...

Okay, moving on now, because that felt weird.

Putting the "coding" in the blog

The other thing that made me reach for Cryogen was its Klipse integration. Klipse, otherwise known as the gods' gift to blogging coders who want to provide an interactive experience to their readers, is an embeddable client-side code evaluator written in Clojure.

You activate it in config.edn for selected languages thusly, converting selector_eval_XXX to selector-eval-XXX and .language-klipse-eval-YYY to .klipse-YYY:

:klipse {
    :settings {
        :selector ".klipse-cljs"
        :selector-eval-php ".klipse-php"

When writing a post which requires Klipse integration, you need to modify the post header, which is a Clojure map (where you can find the post date, post title and draft status among other things.) You add a new key with an empty map as a value: :klipse {} and write your code in the post body in the usual Markdown triple-backticks. Immediately after the backticks, add klipse-cljs for Clojure, or klipse-php for PHP. It just works. Magic.

Light customisation

It's very easy to add extra attributes to a post or a page: you modify the header in the markdown file in a similar way to how you enable Klipse integration, above. The new properties become available in the templates. In this way, I quickly added the ability to display "header image" for a page.

All in all, a pleasant setup and development experience. If you're looking for a simple setup, I would recommend Cryogen :)

Tags: clojure hack