Introducing Loathsxome: minimalist weblog software
By Abhijit Menon-Sen <email@example.com>
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
(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
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.
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
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.
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
Here's a quick summary of the installation process:
- Place loathsxome.cgi in your cgi-bin directory
- Edit the file and set values in the configuration section
- Create the data, plugin, and plugin state directories
- Create template files, or edit the built-in templates
- Copy plugins to the plugin directory
- Optional: set up mod_rewrite rules for nicer URLs
- Optional: set up git trigger to update the entry cache
For more details, see the INSTALL file in the distribution.
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
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.
Some of Loathsxome's functionality is implemented by the following
plugins, which are all included in the distribution along with basic
- Show entries matching a date specified in the URL
- Show entries matching one or more tags specified in the URL
- Automatically tag posts based on the directory they are in
- Split index views into pages and provide links to older and newer
- Display "Read more" links for selected long posts
- Defines values for the title and heading
- Defines some formatted date values for a post
- Don't display posts tagged "preview" unless they're asked for
- Process "meta: " lines in posts (this is how posts are tagged)
- 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.
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:
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.)
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.