Directory Types
awb recognises three different directory types, and builds them differently.
Normal
In a normal directory, all files ending in “.txt” have the template and subtemplate applied, and are then converted via AsciiDoc into HTML files.
If there is no index.txt file in the directory, one will be created, listing the subdirectories and documents in the directory in alphabetical order.
Blog
awb’s blog framework is quite flexible, although for obvious reasons it can’t support reader comments. All you really need to do is to create your blog posts, one per file, using a logical naming structure. The index.html file (showing your most recent posts) and contents.html (listing the titles of all posts, with headings each month) are automatically generated for you.
awb uses the path of a post to determine its date. All the path separators are stripped out, leaving a string of digits which are interpreted as follows:
- 8 digits: yyyymmdd
- 10 digits: yyyymmddhh
- 12 digits: yyyymmddhhmm
The following paths all produce valid dates.
2007/10/12/13/15.txt
2007/10/121315.txt
2007/1012/1315.txt
200710121315.txt
This system leaves you with a lot of flexibility as to how deeply you want your directories nested.
The first line of the post file is taken as the title of the post. This title is used in the recent posts list and in contents.html. This is consistent with the AsciiDoc markup that you would normally use.
In addition to this standard blog format, awb also supports a magazine-like blog formatting feature. In this model, a collection of posts belong to a magazine, which has its own “table of contents” post which can be used to summarise and/or introduce the other posts.
You define a magazine-like blog simply by including a post with a .mag.txt extension. Each .mag.txt file is a magazine “table of contents”. All posts earlier than a .mag.txt post (and later than the previous .mag.txt post) belong to that magazine. Posts later than the latest .mag.txt belong to a virtual magazine entitled “News”.
Gallery
When a directory is specified as a gallery, files with the extension .gal.txt are treated specially. Each .gal.txt file is a room in the gallery, and is formatted as shown in the following example:
[room]
title: The title of the room.
intro: Some text introducing the room.
[filename.jpg]
title: The title of the photo.
caption: A caption for the photo.
When awb encounters a gallery room, it creates a HTML file for each image, using that image’s name. Then it creates a file for the gallery room showing each image in the room. It is up to you to set up templates to point to the appropriate places for each image. For example, I structure my galleries something like this:
siteroot/
galleries/
a_gallery/
a_gallery.gal.txt
big/
pic_1.jpg
pic_2.jpg
small/
pic_1.jpg
pic_2.jpg
The template for photos in a gallery room adds the ‘small’ directory to the path, and the template for individual photo files adds the ‘big’ directory to the path.
The title, intro and caption values are optional, but if you don’t use them, don’t include them in your templates either.
If you are inserting the meta description tag, the intro is used as the room description, and the caption is used as the photo description.