About the notablog content management system

Steven J. Owens, 12/26/2003

notablog is a minimalist tool to let me easily and quickly present a series of articles and essays via the web; a sort of web column.

notablog is open source and available under the apache open source license, and lives at darksleep.com/notablog. I do ask that you include a "powered by notablog" link in your site template.

notablog is geared towards letting me just write an article as a plain text file, using some very simple formatting tags and additionally whatever HTML tags I want to use, throw it in a directory and ignore it and expect notablog will Do The Right Thing.

There are blogging packages out there that are featureful and fine, like MT (MovableType); well-supported by a large community, with lots of features, plug-ins and options. There are wiki packages out there like twiki and owiki, also well-supported by a large community, with lots of features, plug-ins and options.

notablog, on the other hand, is very simple, lean, clean, and does exactly what I need it to do, and no more.

Since I've written notablog, I've decided to make it available as a very, very simple set of CGI scripts for other people to use. When I decided to do this, I had to stop and think about whether there's any real justification for notablog to exist as a distinct application. Does the world really need it?

I decided the reason was simplicity, minimalism and ease of use. From the moment I made that decision, I've done my best to keep it simple - when a feature idea occurred to me, I asked myself if that feature was really necessary, and if a user who wanted that feature wouldn't really be better off getting a real tool, like MT.

I've also been careful to avoid adding nifty chunks of features that would involve adding a library to the package. Libraries aren't that hard for the user to install, or to bundle with the download, but since notablog's entire raison d'etre is simplicity...

Think of notablog as a starter kit. If you have fun with notablog, then you can think about investing the time and energy to set up MovableType or some other more complex CMS. Or you can start from notablog and hack it to do exactly what you want.

Getting, Installing and Using notablog

notablog consists of nine files and a directory full of your articles.

To install notablog:

You're done. If you want, you can edit template.html and make whatever style and color changes you want. Please don't remove the "powered by notablog" link, though you're welcome to change the colors, font styles, etc, to suit your site's design. See "Writing Your Own Template File" for info on what's inside template.html.

That's pretty much it. Now you just start writing articles and saving them in the articles subdirectory. notablog does the rest.

See the "Components" section at the end if you'd like to see more detail on what does what.

notablog Markup Example

title: Complexity In Software
category: software, general
status: private draft
blogdate: 12/21/03
blogentry: An example blog entry

There seems to be this *never-ending* debate between software developers
and the rest of the world, which boils down to the rest of the world
saying "why can't you get your act together like the rest of us?" and
the software developers saying "because software is _different_ - it's
really, really hard."

Note:  I'm going to try to include some specific markup examples in this.

- some
- arbitrary
- bulleted
- text

I read a column, a day or two ago, by Alan Cooper, author of _The
Psychology of Everyday Things_ (later retitled to the friendlier _The
Design of Everyday Things_) and _About Face_, both quite popular works
in the area of cognitive design.


A horizontal rule, just for laughs.


In this column, Cooper says that programmers are craftsmen, in the
older sense of the word - not the devalued craftsmen of the modern
industrial age, but the skilled creators of the pre-industrial age.
He says that programmers aren't engineers, because engineers are
essentially problem solvers, they don't actually build things.
"Engineers don't build software; programmers do."

Foo Markup Tags

The body consists of paragraphs separated by blank lines. Certain special characters are translated to HTML markup. Normal HTML is left alone.

The title is loaded from the title header. If there is no title header (or for .txt files, no headers at all). the title is generated by taking the file name, lopping off the extension, and replacing underscores (_) with a space.

foofile format

notablog expects files to be in foofile format, which is basically a simple-minded version of standard email format (rfc 822):

For a text file (or really, for any file with a name that doesn't end in .foo or .html) the foofile just skips the header step.

For an HTML file, the foofile skips parsing and formatting entirely and just displays the file.

Headers that notablog uses:

Writing Your Own Template File

The template file is really just a simple HTML file. When fooformat is used to format an article, it does the following four replacements on the template file:


notablog consists of the following pieces:

Visible pieces:

index.cgi script that loads all the files in the article directory as foofiles and generates a list of blogentries based on the articles' blogdate and blogentry headers
alphabetical.cgi generates an alphabetical-by-title list of links.
category.cgi generates a list of article links sorted into categories, according to the category headers in the article files.
chronological.cgi generates a list of article links sorted by date.
format.cgi all of the above links point to format.cgi, which loads a file with foofile and formats the foofile with fooformat, then inserts it into template.html and prints it out

Behind-the-scenes pieces:

conf.pl contains configuration info, including defining the names of the articles directory and the template file
articles directory contains the blog entries
template.html simple HTML file that is used to produce the pages.
buttonstyle.css contains a CSS stylesheet used for the buttons in the template
foofile.pm object that is used to load and parse article files
fooformat.pm object that is used to format object files for output.

My to-do list

Blue-sky to-do list