Tutorial: Blosxom

I’ve been thinking lately about my experience learning to do things on the web (both in the past and the more complex things I’m trying to learn how to do now) and it seems that I’m in kind of a good place to write some really useful tutorials. There’s some things that I know how to do that a lot of other people don’t, but I only learned how to do them pretty recently and so none of the skills involved seem natural (and therefore not requiring explanation) to me. Also, I still remember really wishing that there had been clear explanations of these things around when I was trying to do them. Where “geeks” relish figuring out fiendishly hard technical problems without any help from anyone, I think there are a lot of people like me who just want to get things done with some web technology without having to re-invent the wheel themselves on every project. There may be a market larger than just me for tutorials aimed at “beginners” that don’t talk down, that don’t just walk you through doing things without explaining what’s happening, and that do let you accomplish some useful things on the web while learning as much more as you can take about the larger contexts.

Recently, a non-technical friend with a growing interest in the web, asked me to tell him about the system I use to publish this blog. I thought I’d try to turn my response into my first tutorial aimed at meeting the criteria I just set out. So, without further ado, a tutorial on the blog hosting system, called Blosxom.

I run Ideas For Dozens via a blog hosting system called Blosxom (pronounced “blossom”, but spelled with OSX in the middle). It was designed by Rael Dornfest, one of the guys who runs O’Reilly (a technical publishing, conference, and education empire).

The way Blosxom works is through plain text files and something called a CGI script (stand for Common Gateway Interface). Basically the CGI is a little program that processes the posts I write as individual text files into the blog that ends up getting displayed when you come to Ideas For Dozens. What that means in practice is that there’s a file called blosxom.cgi that lives on my webspace (which is provided to me by Speakeasy, my service provider, and which I access through an SFTP program called Fugu [SFTP stands for Secure File Transfer Protocol — i.e. a thing for moving files around which keeps your secrets]). Bloxom.cgi is just a text file has two parts, a human readable part at the top where you enter in information to set certain options and to provide details about your situation, and a bunch of code underneath that actually does the work and that I don’t ever worry or think about (mostly because I don’t understand it).

So, here were the steps for me to get my blog up and running:

1. I downloaded the blosxom.cgi script from their website
2. I copied it onto my Speakeasy hosting space using Fugu
3. I created a folder on my Speakeasy space called “blosxom”
4. I created files inside that folder called head.html, date.html, footer.html, and story.html (as instructed by the tutorial on the blosxom website)
5. I edited blosxom.cgi to enter in the name of my blog, the location of the folder that I’d created, and a few other things that it asked for (the Jefferson quote at the top, etc.)

Then, in order to post, all I have to do is to put a text file in the blosxom folder on my Speakeasy space. The blosxom.cgi script turns any text file in that folder into a post. It takes the top line of the file as the title and the rest of the post as the body. If I create folders or sub-folders in the blosxom folder and put posts in them, the script treats those as “categories” (that’s why posts will say “/useful/web” at the bottom of them).

Now, having done all this will not result in a blog styled like mine. It will result in a plain text blog with the title at the top and the posts stretching the whole length of the window, and the sidebar stuff who knows where (although there is something appealing about plain html layout in its cleanliness). The last big step, which is where the styling and layout come in, is to edit the three template files you created in the setup: head.html, date.html, footer.html, and story.html.

Accomplishing this section of the setup is going to require writing some HTML and CSS, two flavorsx of “markup,” the system for creating written instructions that determine the design and layout on the web. It is obviously somewhat beyond the scope of this tutorial on Blosxom to include a full tutorial on either HTML or CSS. Many excellent tutorials are available (W3Schools is a good place to start). That said, I’m going to give you a tiny taste of CSS just to explain some of the context of how it works within Blosxom (hopefully if you’re not familiar with HTML or CSS it will be enough to almost give you a sense of how Blosxom works and if you are already fluent in them it will be more than enough to really annoy you).

The way blosxom displays your blog is as follows: it starts with head.html, then it displays all the appropriate posts (based on the options you selected in the cgi) using story.html as a template. Then it puts in date.html every time a day changes (i.e. between posts that were written on different days). And it finishes up by putting in footer.html at the bottom. The entire style of my blog comes from some CSS that I wrote that goes at the top of head.html. CSS stands for Cascading Style Sheets and is a relatively new (3 years?) system for doing layout on the web. The way it works (in super-oversimplified-summary mode) is that you define individual styles, by dictating their design characteristics, at the top of your document and then apply them wherever you want on your page. Here’s an example from my blog. At the top of head.html (because that’s the file that the script is going to look at first) I wrote:

#sidebar {
width: 20%;
float: left;
padding-left:.5em;
padding-right:.5em;
font-family: sans-serif;}

What’s happening is that I’m creating a style called “sidebar” (which is, obviously, intended for my sidebar) with certain attributes. It should take up twenty percent of the width of the page; it should “float left,” which means that other content should flow around it to the right; it should have internal padding (the distance of the internal content from its bounding rectangle) of one-half of a tab on the left and right sides; and it should use a sans-serif font.

CSS is not a very complicated subject but it is a very large and detailed one, so all I’m going to say about it here is to explain way you apply these styles in the rest of your page. All you have to do is put <div=”sidebar”> before the content you want to be displayed in this style and then &#60/div&#62 when you want to stop displaying stuff in it. In practice, it looks like this:

<div id="sidebar"&#62
&#60h6 style="margin:0px; padding:0px;"&#62ABOUT</h6&#62
&#60hr&#62
&#60img src="http://www.speakeasy.org/~gborenstein/profile.jpg"&#62
&#60p style="font-size: 10px;"&#62
I like things that work.
&#60br&#62
. . .
&#60hr&#62
&#60a href="http://www.haloscan.com/"&#62&#60img width="88" height="31" src="http://www.haloscan.com/halolink.gif" border="0" alt="Weblog Commenting and Trackback by HaloScan.com" /&#62</a&#62
&#60/div&#62

If you look at the code inside the &#60div&#62 tags, you can see the beginning and end of my sidebar (I’ve skipped most of it since it’s really long): the first line displays the word ABOUT and sets its size, margin, and padding; the third line (that starts &#60img src=. . .) displays that picture of me, etc. At the bottom of the sidebar, right before the &#60/div&#62 tag, you can see that I’m displaying the Haloscan logo as a link to their site (the &#60img&#62 tag is surrounded by &#60a href&#62 and &#60/a&#62 tags).

I find that the best way to proceed with CSS is trial and error. It’s often hard to predict just what a change in a certain attribute is going to do, so you end up going ahead and making the change, checking to see if the result is what you want, and altering it if it’s wrong. The advantage of CSS over old-fashioned table-based ways of doing HTML layout (for example, the At Dusk website) is that it is more “liquid”, things move around more fluidly based on how big the things around them are. The disadvantage of this is that everything’s position is dependent on everything else’s.

The other word of advice I’d give for someone trying to style a Blosxom blog, is just imagine that the whole thing was one big text file with story.html appended onto the bottom of head.html and footer.html appended onto the bottom of story.html, and so on. That will often explain why strange things are happening to your layout.

Now there are a couple of other things that I do on my blog that I won’t go into detail on here. The “ARCHIVES” section is run by a Blosxom plug-in that is pretty easy to figure out if you read the details on their site (I think I may also use a time plug-in to display the time stamp on each post, but I can’t remember). Also, I display <a href="http://del.icio.us/atduskgregmy del.icio.us links through a service provided by a site called RSS Digest that parses RSS feeds and lets you style and display them. They explain how to use their service pretty well. And my Flickr images. come from a Flickr “badge” they provide, which is also not hard to figure out. There are a lot of things like that designed to help you display certain kinds of info on your blog.

So, I guess it makes sense to conclude with some of the pros and cons of blosxom. The good things about it are that the posts are just plain text, so you can create them offline in any text editor of your choice and you’re not dependent on some bloated web interface or a program that you have to pay for. Also, you have as total control over the display as you would over any other webpage you might make. You don’t have to fight a premade template or design via a limited set of options in a web form. It is also totally free (not counting hosting) and native to OSX. The disadvantages are that post management is basically non-existent. For example, recently I accidentally opened and re-saved an old post (Quicktime. . .emitkciuQ), and since the date/time was reset, it jumped to the top of the blog. There’s no way to move it back now or manage post order in anyway as far as I know, which also means you can’t do timed publication or any other sophisticated thing some other systems let you do (you could accomplish some of these things using more advanced operating system technologies [chron jobs] but if you’re at that level of sophisticaiton, you probably didn’t need this tutorial). Also, since there is basically no interface (bloated or otherwise) it doesn’t offer any of the features that a lot of the more hand-holding systems offer: like automatic pinging of Technorati and other blog tracking services, category management, easily implemented search, etc. All said, Blosxom does provide a good combination of low price (being free), simplicity of use, degree of control, and relatively full set of features. It is not as strong in any single one of these areas as some other solutions (a full comparison of most options is available here), for me I found that it held the best combination.

Tagged: Blosxom, tutorial, blog, content management system, cms