Blosxom gives you two flavours right out of the box: a basic default HTML view and an XML-based RSS view for syndicating your blog.
I've also created a Blosxom Flavour Sampler, consisting of a couple-three sets of flavour templates (we'll talk about those in a moment) to get you going.
The default HTML view--by design, mind you--simply cries out to be altered. An earth-shatteringly bland white background with your blog title in large letters. Posts are functional, albeit also a little bland:
Your typical Blosxom post consists of a required title
on the first line and any manner of text and HTML
markup in the body.
posted at: 11:33 | path: / | permanent link to this entry
Thankfully, re-decorating is quite simple. There are only two bits of information you need to understand: template components and template files.
Template components are chunks of dynamic content made available to you by Blosxom.
$blog_title, for instance, is a placeholder for what you set as the title for your blog during configuration; wherever that appears in your flavour template, it is replaced on the fly with its proper value.
Template components come in two forms: global and story.
...global template components
Global components are available for your use in any of the template files. Some are set in the Blosxom configuration, while others are generated on-the-fly:
The title of your blog, as set in Blosxom's configuration.
e.g. My Blosxom Blog
The description of your blog, as set in Blosxom's configuration.
e.g. A blog about this and that.
The language code set in Blosxom's configuration.
Your blog's URL, as determined automagically by Blosxom or set explicitly in Blosxom's configuration.
The requested view, a path or date or combination thereof.
The requested flavour.
...story template components
Story components are specific to the particular story/blog entry at hand and, so, change from story to story.
The title of a blog posting.
e.g. Typical Post
The body of a blog posting--everything beyond the first line (title) of the file.
e.g. Your typical ... in the body.
Your blog's URL, as determined automagically by Blosxom or set explicitly in Blosxom's configuration. This is actually a global template component, but useful for constructing permalinks to stories, and so listed here too.
The path in your blog's directory/folder hierarchy at which the post lives.
$yr, $mo, $mo_num, $da, $hr, $min
The date/time at which the post was written, expressed as year, month (
Dec), month numeral (
12), day (
31), and time in hours (
23) and minutes (
e.g. 2002, "Dec", 12, 01, 11, 33
The post's filename, without the file extension (usually
With that under our belts, we'll step through a sample HTML flavour, introducing you to the various bits and bobs as we go along. Remember that all of these files don't yet exist as the default HTML view is built-in (it actually lives in the
blosxom.cgi script itself, if you can believe that). By creating a new HTML view, we're overriding the built-in version.
A Blosxom template consists of a head (all the stuff before your posts), foot (all the stuff after), story (the formatting for an individual post), content_type (sets the content type of a particular flavour), and (optionally) date (controls the look of daily datestamps). These exist in simple text files named, appropriately enough: head, foot, story, content_type, and date.
But Blosxom allows for more than one flavour, so each threesome must somehow be associated together. Thus, for an HTML flavour, we have:
date.html. Simple, eh?
The header, as I mentioned, is everything appearing before you stories themselves. The header for the HTML flavour makes its home in a file called
head.html in your data directory.
Here's a nice sample
head.html to get you going:
<hr size="1" noshade />
Copy-and-paste this HTML to your favourite text editor and save it as a plain text file to
datadir is your Blosxom data directory.
$blog_title bit? That's one of the global template components mentioned further up this page.
Just as the header contains everything appearing before the stories, The footer contains everything you'd like to appear after. The footer for the HTML flavour lives in a file called
foot.html in your data directory.
Here's a nice sample
foot.html consisting of a nice horizontal line and "powered by blosxom" button:
<hr size="1" noshade />
Copy-and-paste this HTML to your text editor and save it too as a plain text file to
Reload your Blosxom page and notice the difference.
Of course its not written anywhere that you must include a "powered by blosxom" button on your page, but it's a nice way to identify yourself as a Blosxom user and point the way to Blosxom for anyone who's interested in starting their own weblog.
The look-and-feel of each story is specified in the story template,
story.html in your data directory. Let's spice up that default story layout a little using some prettier HTML and the story template components available to us, shall we?
<a href="$url/$yr/$mo_num/$da#$fn">permanent link</a></i>
...the story ...permalinks
A word about permanent links, or "permalinks". Permalinks provide a permanent URL for others to use when referencing one of your postings that promises never to change. While stories my drop off the bottom of your weblog's home page -- remember, they're presented in reverse-chronological order -- the permalink assures a link will withstand the ravages of time and template.
Blosxom's default permalink style is date-based (as shown above). For example, a story saved to the file
a_story.txt on January 1st, 2003 is permalinked as
http://www.example.com/cgi-bin/blosxom.cgi/2003/01/01#a_story. This brings up a page with only stories from that day and directs the browser to hop down to the right story (the
#a_story bit). To accomplish this kind of permalinking, your story template should include something like:
<a href="$url/$yr/$mo_num/$da#$fn">permanent link</a>
You may prefer to use path-based permalinks. A story saved to the file
a_story.txt in the directory
datadir/fiction would be permalinked as
http://www.example.com/cgi-bin/blosxom.cgi/fiction#a_story.txt. For this type of permalinking, your story template would include something like:
<a href="$url$path/index.$flavour#$fn">permanent link</a>
You can also permalink to an individual story appearing all on its own. This is a modification of the path-based permalink. Your story template would include:
<a href="$url$path/$fn.$flavour">permanent link</a>
The default content-type encoding -- what Blosxom tells your browser the type of output its about to see is -- is Plain Text (
text/plain, to be precise). If you wish to create a template with different encoding (e.g.
text/html), you'll need to create a
content_type.flavour file (where
flavour is the flavour you're working with) specifying so.
For our example (an HTML flavour), the content-type should be
text/html, specifying that this is to be interpreted by the browser as an HTML document.
Copy-and-paste the following to your text editor and save it as a plain text file to
If, for example, you were creating a custom XML flavour for your weblog called "exemel" which should be of content-type
text/xml, you'd simply create a file called
datadir/content_type.exemel containing the one line:
Prepended to each day's clump of entries is a date-stamp. The default look-and-feel for the date-stamp is:
Wednesday, 01 Jan 2003
If that suits you, feel free to skip creating a
date.html template file. Otherwise, go ahead and alter it using any of the story template components relating to date:
Perhaps, for instance, you prefer an italic, purely numeric date for your HTML flavour. Copy-and-paste this HTML to your favourite text editor and save it as a plain text file to
datadir/date.html, where datadir is your Blosxom data directory.
a wealth of flavours...
Don't wander off quite yet. There's a little something else you should know about flavours... there is a wealth of them, limited only by your interest and ingenuity. While the HTML and RSS flavours come right out of the box, you can create any flavour of your choosing simply by creating a
content_type.flavour, and (optionally)
date.flavour for each,
flavour being your preferred flavour name.
Want a "circa 1993" flavour to cater to older browsers? Create
story.1993 files in your data directory just as you did for the HTML flavour above. How about a "titles only" view of your weblog, displaying only the titles and none of the other details for each entry? You guessed it:
To view a particular flavour, tack either
The preferred form is
flavour is the flavour at hand) on to the end of your Blosxom URL. So, for example, the 1993 flavour might be found at either
?flav=flavour variation being provided for backward compatibility with older versions of Blosxom.