Introducing Loathsxome: minimalist weblog software

By Abhijit Menon-Sen <>

I started using Blosxom a few weeks ago. I liked the basic idea (that each post is one file) very much, but I found the code hard to read and poorly documented. Plugins varied widely in quality, and I had to jump through hoops to implement some of the things I wanted. By the time I got everything working the way I liked it, I ended up with a complete rewrite.

The code is well-documented, supports tagging and pagination, generates an RSS feed, works nicely with Git, and lets me publish URLs like http://toroid.org/etc/200908 and /etc/birds+language. (Disadvantages: it isn't quite plugin-compatible with Blosxom, and it doesn't support static generation.)

I'm sure I could have used a more modern, featureful program to achieve the same effect, but I'm glad I didn't have to. I was happier to spend a couple of hours writing something worse than a few days trying to fit something better, like Wordpress, into my head.

I wrote this code for my own use with no intention of releasing it, but a few people have expressed an interest in using it, so here it is.

No longer maintained

Update (November 2013): Loathsxome never had more than a handful of users, and only two who regularly contributed code (Arnt Gulbrandsen and myself). Arnt wrote plusxome, and I wrote something else using Mojolicious without even pretending to maintain backwards compatibility.

Loathsxome is still here. It works as well as it ever did, and none of what's written below is untrue, but nobody uses it any more.

Features

Loathsxome knows how to display two kinds of things: a single journal entry or post, and an "index view" or list of posts (all posts, or those that match some criterion, such as "tagged with 'horror'" or "written in May 2009").

Loathsxome features nice-looking URLs, support for tagging and categorisation by directory, RSS feed generation, "Read more" links for selected posts in index views, HTML entity encoding, and so on. If you use Git to maintain your web site, as I do, you'll find that Loathsxome works very well with it.

The code is easy to follow, and well-documented; the plugin system is simple but powerful. Plugins can affect any aspect of the program's operation, from URL parsing to post selection and rendering.

Compared to Blosxom

Loathsxome has two significant disadvantages: it is not compatible with existing Blosxom plugins, and it does not support static generation yet. (But the plugin interface is so similar that most plugins can be ported with a few minutes' work; and I intend to implement static generation in a future release.)

Existing Blosxom users may find little reason to switch, especially if they have invested some effort into selecting and configuring plugins. But it takes real work to configure Blosxom to duplicate Loathsxome's default behaviour, so new users who like that behaviour can save time by using Loathsxome; and anyone who wants to extend the code will appreciate its improved internal organisation.

Loathsxome also has a more evocative name than Blosxom.

Download

Loathsxome is a CGI program written in Perl (without any CPAN dependencies). This distribution contains loathsxome.cgi and some plugins, described below. It is distributed under an MIT-style open source license. (See the included LICENSE file for details.)

Download loathsxome.tar.gz (from github.com/amenonsen/loathsxome)

Installation

Here's a quick summary of the installation process:

For more details, see the INSTALL file in the distribution.

Documentation

I am aware that Loathsxome has inadequate documentation, and I consider this a serious bug. The source code is well-documented, but there is no user manual. I wrote the program for myself, at first with no intention to release it, and later with no expectation that more than a few of my friends would use it. But that is not an excuse for poor documentation, and I would like to improve it.

Suggestions are welcome. Please let me know if you have questions about any aspect of installing, using, or extending Loathsxome. I will try to answer them and use the answers as the basis for better documentation. (Knowing that the documentation would actually be useful to someone would provide motivation to write it.)

In the meantime, the Blosxom documentation may be useful. Most of the ideas translate directly, but the details may differ slightly. If you are at all familiar with Perl, the source code may help to explain those details.

Maintenance and feedback

Loathsxome does most of what I want from it, but I still enjoy working on it, and intend to add features as needed. I already know that I want to implement static generation and port or modify a few Blosxom plugins (e.g. archive links, search, and support for Atom feeds).

But in deciding what to do, I will pay more attention to features that people ask for, so if you use Loathsxome and would like to see something work differently, please send me mail, and I'll try to help. Questions about the code or how to use the program are also welcome.

If you find Loathsxome useful, I would be delighted to hear about it.

Plugins

Some of Loathsxome's functionality is implemented by the following plugins, which are all included in the distribution along with basic documentation.

filterdate
Show entries matching a date specified in the URL
filtertag
Show entries matching one or more tags specified in the URL
autotag
Automatically tag posts based on the directory they are in
paginate
Split index views into pages and provide links to older and newer pages
readmore
Display "Read more" links for selected long posts
pagetitle
Defines values for the title and heading
fulldate
Defines some formatted date values for a post
hidepreview
Don't display posts tagged "preview" unless they're asked for explicitly
metadata
Process "meta: " lines in posts (this is how posts are tagged)
entrycache
Maintain a cache of file properties

Loathsxome looks for plugins in the configured plugin directory, and loads them in alphabetical order. If you want to change that order, you can rename the plugin file to 01foo to cause it to be loaded before 02bar. You can temporarily disable a plugin by renaming it to foo_.

The distribution includes an example plugin that explains how and when each plugin function is called, and what it is expected to do. It also includes a bundle that contains all of the plugins mentioned above. In actual use, you may want to use the single plugin to reduce the number of files that must be opened to render each response.

Let me know if you have any questions about these plugins, or if you need help with writing your own plugins, or porting Blosxom plugins.

Git integration

I keep my web site in a git repository, and push changes to a repository on my web server. I wanted to keep my journal entries in the same place, but git makes no attempt to preserve file mtimes, so posts were sometimes re-sorted inappropriately. I looked at the various mtime-caching plugins for Blosxom, but didn't like the way they worked. So I rolled my own solution.

I wrote a plugin which read "filename: mtime" lines from a file and used those values instead of the real mtimes. Next, I added "meta: date=NNN" lines at the beginning of each post (removing them before display using another plugin), and wrote a script to create the mtime cache based on that data. Finally, I set that script up as a post-commit hook, so that every time I changed (or added) a post in the repository, a "meta: date=NNN" line would be added based on the current mtime, and the cache (also under version control) would be updated automatically. This scheme works well for other kinds of metadata too (e.g. "meta: tags=birds,language").

The distribution includes the post-commit hook I use, and instructions on how to set it up.

(There's one mild complication. The way I have my repository set up, the Loathsxome data directory is under my web site's DocumentRoot, which it really shouldn't be. I papered over the problem with a "Deny from all" in the relevant htaccess file, but if I had to do it over, I would put it outside the DocumentRoot altogether.)

History

I first heard of Blosxom in 2004, and I liked the idea enough to return to it when I needed something like it five years later. I spent a couple of weeks trying to configure it—and a handful of plugins—to my liking, but I spent too much time trying to understand and fix bugs in the old code, and ended up rewriting most of it while trying to add tagging support and implementing the entry cache.

I did not want to rewrite Blosxom, but the reduced maintenance burden is sufficient to justify the effort. Loathsxome does exactly what I want. I did not intend to release it, but a few people have already expressed an interest in using it, so here it is.

Thanks to Mike Acar for his help during the preparation of the first Loathsxome release.