man blazetheme (7): an introduction to BlazeBlogger theme creation

DESCRIPTION

This document tries to provide a brief introduction on how to create new or modify existing theme for your BlazeBlogger web presentation.

BlazeBlogger Theme Structure

To make it as easy to alter as possible, BlazeBlogger theme consists of two parts: the template file located in the ".blaze/theme/" and corresponding stylesheet in the ".blaze/style/" directory. This way, you can easily switch between different styles (e.g. bright and dark one) without even touching the template file, which generally does not tend to vary much.

Creating the Template File

The template file is where the page layout is described. It is a bare HTML (or XHTML, it really does not matter) file with various placeholders to be substituted by appropriate data. Most of the placeholders are just ordinary HTML comments with a reserved strings in them. Note that while the case is not significant, the fact that the whole placeholder has to be on a single line is.

For the example usage, see the default template file.

List of Head Placeholders

These are the placeholders that usually appear in the HEAD section of the HTML/XHTML document.

: The Content-Type META tag.
: The Generator META tag.
: The Date META tag.
: The Stylesheet LINK tag.
: The RSS feed LINK tag.
: Current page title, usually used inside TITLE element.

List of Body Placeholders

These are the placeholders that usually appear in the BODY section of the HTML/XHTML document.

: The blog title, see "blog.title" in the BlazeBlogger configuration.
: The blog title, see "blog.subtitle" in the BlazeBlogger configuration.
: The user's name, see "user.name" in the BlazeBlogger configuration.
: The user's e-mail, see "user.email" in the BlazeBlogger configuration.
: The current year.
: List of tags.
: List of months.
: List of pages.
: List of recent blog posts.
: Main content (e.g. post or page body, posts listing etc.).
%root%: Relative path to the root directory of the blog; to be used inside links. Note that this placeholder can safely appear in the post/page body as well and will be still taken into account.
%home%: Relative path to the website home (index) page; to be used inside links. Note that this placeholder can safely appear in the post/page body as well and will be still taken into account.
%page[id]%: Relative path to the page with given id; to be used inside links. Note that this placeholder can safely appear in the post/page body as well and will be still taken into account.
%post[id]%: Relative path to the post with given id; to be used inside links. Note that this placeholder can safely appear in the post/page body as well and will be still taken into account.
%tag[name]%: Relative path to the tag with given name; to be used inside links. Note that this placeholder can safely appear in the post/page body as well and will be still taken into account.

Creating the Stylesheet

The stylesheet is just a plain CSS file (CSS 2.1 is recommended, although not required) with most of its parts dependent on elements, classes and IDs introduced in the theme file. Those few that are produced by the blaze-make(1) are described below.

For the example usage, see the default stylesheet.

List of Obligatory Classes

post: "H2" element containing the page/post title.
section: "DIV" element containing the name of the current section (e.g. monthly archive, tag listing etc.).
information: "DIV" element, optionally containing the additional information about the post, such as the date of publishing, the post author, or the list of attached tags. It is placed above the post, right below its heading.
post-footer: "DIV" element, optionally containing the additional information about the post, such as the date of publishing, the post author, or the list of attached tags. It is placed right below the post itself.
date: "SPAN" element containing the date of publishing.
author: "SPAN" element containing the post author.
tags: "SPAN" element containing the list of attached tags.
previous: "DIV" element containing link to the page with older posts.
next: "DIV" element containing link to the page with newer posts.
more: "A" element containing the `Read more' link.

FILES

.blaze/theme/: BlazeBlogger themes directory.
.blaze/style/: BlazeBlogger stylesheets directory.

AUTHOR

Written by Jaromir Hradilek <[email protected]>

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

A copy of the license is included as a file called FDL in the main directory of the BlazeBlogger source package.