27th dimension of the Internet


by , on

1 Building a blog on Git hooks

I did not want to write plain HTML pages from scratch for this blog. But I did not want to use a big CMS either: like many webmasters nowadays, I had a prior experience with Wordpress, but I found it too heavy, too much like an “overkill” solution. So I had a look at static blog generators, known to keep things simple. There is an interesting list here, which categorizes most of such well-known generators by language, written not too long ago (May 2014), with equally interesting sources. I tried several ones of them, mostly those based on Node.js (I would like to get more familiar with this platform). But nearly all of those “light” frameworks needs several dependencies (npm or pip packages, Ruby gems…), and the size of a bare install directory is generally above 30 megabytes. Then I tried fugitive.

Fugitive, besides being the name of a known Git wrapper plugin for Vim editor, is a blog engine running on top of Git hooks. It was made by Pablo Rauzy for his own blog. This software is the lightest blog engine I found, requiring no dependencies other than Git. The Git repository currently weights 576 kilobytes, and is still under one megabyte after installation. The concept is simple and smart: on every commit, Git hooks analyze what template or article sources have been modified, and regenerate HTML pages as appropriate. A list of archived blog entries and a RSS feed are automatically updated as well. It may lack some functionalities of other “modern” CMSs, such as tags (I don’t care), CSS preprocessing (not indispensable for simple design) or syntax highlighting for code snippets (pandoc does this for me), but it’s simple, intuitive, and easy to hack.

2 From fugitive to pangitive

I will not create another detailed tutorial here for installing fugitive, the official documentation is pretty exhaustive already. But here are some notes about my own utilization.

The content of the articles is to be written in raw HTML, but there is a very useful “preprocessor” option you can use to indicate how to deal with your source file prior to inserting it into the templates. Concretely, I could use it to process my text with pandoc tool so as to turn markdown text into HTML. With both pandoc and fugitive installed, configuring this preprocessing was as simple as running a single command from the Git repository of the blog:

git config fugitive.preproc "pandoc -t html"

This works great. HTML generated by pandoc is inserted into the templates by fugitive.

But pandoc is also able to do this on its own, and has its own syntax that fugitive partly reimplements. Rather than keeping what I considered as a redundancy, I decided to hack deeper into fugitive hooks. I replaced the HTML generation done by shell tools by a call to pandoc: in this way I am able to access to more features of pandoc tool. But pandoc becomes a mandatory dependency of the tool. So this isn’t like fugitive anymore; this is rather a fork, and I called it pangitive. If you’re interested in it, it is available (and documented) on GitHub.

Some additional personalization I performed and that was added to pangitive includes CSS design (my tastes are not as sober as Paulo’s) and hacking the hooks so as to generate “static” page, in the sense that they are no blog entries and should not be added into the archives or the RSS feed (namely, I used it for the About page).

3 A note about pandoc

Pandoc is a nice tool written in Haskell, able to convert documents from one markup format to another. It has a lot of functionalities, coming at a cost: the binary weights 37 megabytes (in the version I currently use), so I’m not earning much space in regard to another static CMS in the end. It does not represent an issue for me since I already had pandoc installed anyway, and at least I only depend on a single tool (two, actually, since there is also Git) rather than on a list of dependencies that would include many packages.

Other than a man page, there is also an official website.