Gagallium uses the static blog generator Stog, recently released by Maxence Guesdon. The nice thing with using a static blog generator is that deployment is simplified a lot.

Why a static blog generator

The biggest pain in a blog administration is handling the comments. Hunting spam, learning about modern identification protocols, all of this is time-consuming and frankly boring. I believe there are two reasonable choices:

  • host one’s entire blog on a central service that provides spam filtering and moderation tools
  • host the blog locally but offsource the comment handling to a dedicated commenting service that provides spam filtering and moderation tools

The problem with the first option is that it can be limiting in what can be used in the blog. We considered using a centrally hosted Wordpress blog for example, which provide a reasonable set of features (including source code highlighting), but what if we want, for example, automatic type-checking of the OCaml snippets we put on the blog?

I therefore decided to adopt the second option: we use the commenting service Disqus that provides comment administration tools. My main gripe with Disqus is that it’s not free software; there are plans for free alternatives, but nothing ready yet, at least not to my knowledge – I’d be delighted to find one.

Comments really are the only component of a blog that needs to be dynamic. By using javascript to contact the commenting service, we let users handle it, and a static blog is therefore a very compelling option. Dead simple deployment and administration, few security worries, etc.

About stog

Stog is a very young blog generator; as I understand, it evolved from Maxence Guesdon successive hardcoded websites, and was released just a few weeks ago. You have to be ready to hack, and to tolerate a certain level of idiosyncrasy, to use it, but I am overall quite happy; and the hackability is also a feature.

It seemed fun to run a blog on OCaml, though I was initially afraid of intoxication with the Not Invented Here syndrome. I’m sure there are good (maybe better) static blog generators written in other languages, but I think it has potential to become a very reasonable alternative.

Stog makes it easy to highlight OCaml code, have a toplevel run it to check for obvious mistakes and potentially print back results. 

let x = 1;;

# let
y = x;;

val y : int = 1

There is also a preprocessor for LaTeX code, allowing to easily use math formulas. I originally planned to use the nice MathJax javascript layer (client-side rendering of LaTeX), but most syndication feed readers don’t accept javascript.. for now – I hope they start doing it, because otherwise they could be obsoleted, and I like the efficient workflow of RSS/Atom readers.

\[ , ; ; \]

Stog’s design is also quite simple and very reasonable. In the end, it is a metadata-gathering layer (to generate archives, automatically compute previous/next links, etc.) on top of a simple and flexible templating engine, Xtmpl. The code is not pretty (that can be cured), but works well. It is a rewrite engine that transforms an input XML document until it reaches a fixpoint (using Daniel Bünzli’s Xmlm library). The transformation is completely parametrized by the user, which can provide translation functions for any element (say <markdown>).

Stog comes with some predefined active elements (<include file="foo"/>, <if var="val">), and it is easy to add new ones. The discus integration is implemented by providing a <comments/> command, and I have added a markdown processing plugin.

Finally, I have found Maxence to be a nice maintainer to work with: I proposed a few changes, and they have been integrated upstream.

An example

You can look at the source for this post: index.src.html

What is not shown here is the set of templates I wrote to imitate the existing design of the Gallium website. They were adapted from the templates distributed with Stog, which are to the one used to build its website (the complete source for the website can be found in the repository, in doc/). Writing those design templates is an initial investment that takes a bit of time, but hopefully the delightful red stripes will be a big asset for future OCaml propaganda.