Writing a Weblog using PubTal

How to use PubTal to maintain a weblog.

PubTal's weblog support allows posts to be authored using any Content Type that produces a "page/content" property, such as HTMLText or OpenOffice. 

PubTal can generate several different types of page depending on the site configuration, but the layout of the pages is fixed as follows:

Two examples of how to use the Weblog content type can be found in the examples directory.  The basic-weblog example shows the simplest weblog configuration possible, while full-weblog includes all of the features PubTal supports.

Configuration Options

With no configuration options set the PubTal Weblog plugin will assume the following configuration:

1. The weblog index template is None and no index will be generated.

2. No day, month, or syndication templates exist.

3. The weblog is called 'Weblog'.

4. All *.post files are written in HTMLText format, and are in the same directory that the index will be generated in.

5. The latest 5 posts should be included in the weblog index.

General Configuration

The following configuration options are applicable to the whole weblog:

Required Headers

When authoring weblog posts in OpenOffice there are no specific headers required for PubTal's weblog support to work.  It is recommended that the "title" property of the OpenOffice document be used to title the post, but this is not required.

When using any other Content Type (e.g. HTMLText) one of the following headers must be present:

1. CreationDate

2. creationdate

3. creation-date

The value of the header must be the creation date/time of the post, in one of the following formats:

1. Y m d H:M:S.  (e.g. 2004 01 08 17:01:01)

2. Y m d H:M.  (e.g. 2004 01 08 17:01)

3. Y-m-d H:M:S.  (e.g. 2004-01-08 17:01:01)

4. Y-m-d H:M.  (e.g. 2004-01-08 17:01)

Building Weblog pages

PubTal treats all new posts, and all posts that are in the index (i.e. that will appear on the index page), as being part of the "normal" class.  This means that PubTal will check for any changes to existing posts that form part of the index, and check for new posts.

When PubTal detects a changed or new post it will build the index, day, month, and syndication pages as applicable.  If a new post is found that is the first in the month then all day and month pages will be built (configurable - see Monthly Archive Performance Notes).

To build all pages for all posts (for example after changing a template) run the updateSite.py command with the "--all" option.

Template Properties

In addition to the properties available to any other PubTal template, weblog templates have access to the additional properties, and no content property.

Index and Syndication properties.

Index and Syndication templates have access to these extra properties.

1. page

   1. weblog-name.  The name of this weblog.

   2. weblog-link.  The absolute link for this weblog (available if hostname is defined).

   3. monthlyArchive.  A Monthly Archive object holding information useful for providing links to the monthly archives.

   4. days.  A Day object, holding information about the days posts.

Day properties

The Day Template has, in addition to the properties of the Index template, one additional property:

1. dayDate.  This is a Date Object with a default format of "%a[LONG], %d[NP] %b[LONG] %Y".  (E.g. Thursday, 8 January 2004)

Month properties

The Month Template has, in addition to the properties of the Index template, several additional properties:

1. yearName.  The year this month falls in (YYYY format).

2. monthNameLong.  The long form of the month name.

3. monthNameShort.  The short form of the month name.

Monthly Archive Object

Monthly archive objects will only be accessible if a weblog monthly archive is generated, i.e. if the weblog-month-template option is defined.

A Monthly Archive object is a list, with one entry per year.  Only months and years with a weblog post are present in the list.  The properties of each entry in the list are:

1. yearName.  The year that this entry is for as YYYY.

2. monthList - List of month information, with one entry per month.

   1. monthNameLong.  E.g. January.

   2. monthNameShort  E.g. Jan.

   3. monthNumber.  E.g. 1

   4. archiveLink.  The link from the current page to the archive page for this month.

Day Object

Day objects are available to all weblog templates as a list in the 'days' property.  Each entry in the 'days' list consists of the following properties:

1. date.  This is a Date Object with a default format of "%a[LONG], %d[NP] %b[LONG] %Y".

2. posts.  A list of Post Objects that were made during this day.

Post Object

Post objects consist of the same properties that are normally present under the 'page' property for a normal PubTal page of the type used to create the weblog post.  Additionally the Post object has the following properties:

1. permaLink.  This is the link to the post within a day page.  This is only present if the weblog-day-template configuration property is set.  This property is not available in the day template.

2. permaLinkName.  This is the hyperlink anchor name that should be used within the day template to provide a permaLink location.  This property is only available in the day template.

3. absolutePermaLink.  This is the absolute link to the post within a day page.  It is only present if the hostname and weblog-day-template configuration properties are set.  This property is not available when expanding the day template.

4. date.  A Date Object for date/time the weblog post was created.  Default to "%I[NP]:%M %p" (i.e. the time in 12 hour format).

5. id.  This is only available if the weblog-tag-prefix configuration property is set. Used to uniquely identify this post.

Options affecting syndication

RSS 0.91 Configuration

The following configuration options are used by the RSS template (see examples/full-weblog).  Those options listed as Required are needed to build a valid feed.

Content Options

Template Options

For the RSS template to produce valid output the following options need to be specified in a template directive:

Atom 1.0 Configuration

The following configuration options are used by the Atom template (see examples/full-weblog).  Those options listed as Required are needed to build a valid feed.

Content Options

Template Options

For the Atom template to produce valid output the following options need to be specified in a template directive:

Monthly Archive Performance Notes

If the day and monthly templates use the Monthly Archive Object then their output pages must be rebuilt for the first post of every month.  PubTal will do this automatically if the content configuration parameter weblog-month-template is defined.

If the day or monthly templates do not use the Monthly Archive Objects then the time consuming monthly-rebuild can be suppressed.  To do this set the following template configuration parameter: