"Blaaargh!" is a simple filesystem-based content management system for static or semi-static publishing. You can run it standalone (...or will be able to soon) or integrate it as a component in a larger happstack application.

Like the venerable blosxom (http://blosxom.sourceforge.net/) package, Blaaargh! relies on plain-text files on the file system as its content database.

FEATURES:

• simple on-disk content database
• posts/pages written in markdown format
• pages formatted into HTML by a flexible cascading template system based on HStringTemplate (http://hackage.haskell.org/package/HStringTemplate). Page templates can be overridden on a per-page or per-folder basis.
• directories can be given indices using the templating system. Various views of the directory contents (e.g. N most recent pages, pages in forward/reverse chronological order, pages in alphabetical order) are exposed to the index templates.
• directories with defined indices get Atom-format syndication feeds
• configuration parameters (site title, site URL, base URL, etc.) specified in an INI-style config file

MISSING FEATURES:

• a web-accessible "administrative area"
• a comment system (for my homepage I'm currently just outsourcing this to Disqus)

INSTRUCTIONS:

The Blaaargh directory consists of the following contents:

config

an INI-style configuration file

templates/

a tree of .st template files, served by HStringTemplate

content/

a tree of content files. Markdown-formatted files (with .md extensions) are parsed and read as "posts" that are rendered to HTML via the templating mechanism. Other files are served as static content.

Let's say you have some files in here:

     config
     content/grumble.md
     content/index.md
     content/posts/bar.md
     content/posts/bar/photo.jpg
     content/posts/foo.md
     content/static/spatula.md
     templates/404.st
     templates/post.st
     templates/static/index.st
     templates/static/post.st
     templates/static/spatula.st

Think of it like this -- you request content, either a single post, a directory, or an atom feed (hardcoded as /[dir]/feed.xml). Blaaargh searches for the closest matching template.

For .md files ("posts" or "pages"), the templates cascade: e.g. for a file content/foo/bar/baz.md, we would search templates/ for the following templates, in order:

• foo/bar/baz.st

• foo/bar/post.st

• foo/post.st

• post.st

• 404.st

For directories, the templates don't cascade; a directory needs to have a matching template in order to be served. E.g. for a directory /foo/bar/quux, we search templates/ for "foo/bar/quux/index.st", and if content/foo/bar/quux/index.md exists, we read it into the template as content text. (More about this in "TEMPLATING" below.)

CONFIGURATION

A Blaaargh! config file looks like this:

 [default]
 # what's the domain name?
 siteurl = http://example.com

 # blaaargh content will be served at this base URL
 baseurl = /foo

 [feed]
 # site title
 title    = Example dot com
 # authors
 authors  = John Smith <john@example.com>
 # Atom icon
 icon     = /static/icon.png

 # posts on this list (or directories containing posts) won't be included in
 # directory indices, nor in atom feeds
 skipurls = static

Blaaargh! uses the ConfigFile library for configuration and post header parsing. (http://hackage.haskell.org/package/ConfigFile)

POST FORMATTING

Posts are (mostly) in Markdown format, with the exception of a key-value header prefixed by pipe (|) characters. Example:

 | title: Example post
 | author: John Smith <john@example.com>
 | published: 2009-09-15T21:18:00-0400
 | summary: A short summary of the post contents
 
 This is an example post in *markdown* format.
 

Blaaargh! accepts the following key-values for posts:

title

The title of the post

author

The post's author

authors

same as author

summary

a summary of the post

updated

the post's last update time in RFC3339 format

published

the post's publish date in RFC3339 format

The headers are parsed as follows: any lines starting with the | character (up until the first line not starting with |) have the prefix stripped and are sent through ConfigFile.

Please see its haddock for input syntax.

DATA MODEL

The documents get indexed into a key-value mapping by id. (Where an "id" for a post is defined as its relative path from content/, with the .md suffix removed.)

Files with an '.md' suffix are treated as "posts"/"pages", and are expected to be in markdown format. Files with other suffices are served as static files.

TEMPLATING

Blaaargh! uses templates to present the content of posts and lists of posts in HTML.

For an individual post (either postname-specific postname.st or generic post.st), Blaaargh exports a template variable called $post$ which is a map containing the following attributes:

    $id$
    $date$
    $url$
    $title$
    $content$
    $summary$
    $authors$

So in other words, within your template the post's URL can be accessed using $post.id$.

For directory templates (index.st), we collect the posts within that directory and present them to the templating system as a list of post objects (i.e. containing the $id$/$date$/etc. fields listed above):

    $alphabeticalPosts$
    $recentPosts$                -- N.B. 5 most recent posts
    $chronologicalPosts$
    $reverseChronologicalPosts$

Sometimes you want to pass extra key-value mappings to be served in Blaaargh templates. For example:

lift (addExtraTemplateArguments [("foo", "foovalue")]) >> serveBlaaargh

will cause the value $foo$ to be expanded as "foovalue" within templates served by Blaaargh.