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:
Page Type | Location | Notes |
|---|---|---|
Index page. | index.extension | The extension is taken from the template. |
Day page. | yyyy/mm/ddmmyyyy.extension | The extension is taken from the template. |
Syndication pages. | templatename.extension | The name of each syndication page is taken from the corresponding template name. |
Archive pages. | yyyy/mm/archive.extension. | The extension is taken from the template. |
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.
With no configuration options set the PubTal Weblog plugin will assume the following configuration:
The weblog index template is None and no index will be generated.
No day, month, or syndication templates exist.
The weblog is called 'Weblog'.
All *.post files are written in HTMLText format, and are in the same directory that the index will be generated in.
The latest 5 posts should be included in the weblog index.
The following configuration options are applicable to the whole weblog:
Option | Value |
|---|---|
weblog-name | The name of this weblog. |
weblog-index-template | The name of the template to use to generate the index page. |
weblog-day-template | When defined PubTal will use this template to build one page per day. The pages are generated in |
weblog-month-template | When defined PubTal will use this template to build one page per month. The pages are generated in |
weblog-syndication-template | This option can be given multiple times in a single directive. Each option corresponds to a syndication template. See later sections for options required to support the different syndication formats. |
weblog-post-depth | The depth of the weblog's posts from the base directory. E.g. if posts are kept in weblog/yyyy/mm/name.post then weblog-post-depth should be set to 2. The location of the weblog posts is independent of where the resulting day and monthly archive pages are located. |
weblog-index-size | How many posts should be visible on the index page and in the syndication feeds. |
Weblog-index-disabled | Set to True to stop the index page for the weblog being built. |
weblog-content-type | The PubTal content type that posts are written in. Defaults to HTMLText |
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:
CreationDate
creationdate
creation-date
The value of the header must be the creation date/time of the post, in one of the following formats:
Y m d H:M:S. (e.g. 2004 01 08 17:01:01)
Y m d H:M. (e.g. 2004 01 08 17:01)
Y-m-d H:M:S. (e.g. 2004-01-08 17:01:01)
Y-m-d H:M. (e.g. 2004-01-08 17:01)
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.
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 templates have access to these extra properties.
page
weblog-name. The name of this weblog.
weblog-link. The absolute link for this weblog (available if hostname is defined).
monthlyArchive. A Monthly Archive object holding information useful for providing links to the monthly archives.
days. A Day object, holding information about the days posts.
The Day Template has, in addition to the properties of the Index template, one additional property:
dayDate. This is a Date Object with a default format of "%a[LONG], %d[NP] %b[LONG] %Y". (E.g. Thursday, 8 January 2004)
The Month Template has, in addition to the properties of the Index template, several additional properties:
yearName. The year this month falls in (YYYY format).
monthNameLong. The long form of the month name.
monthNameShort. The short form of the month name.
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:
yearName. The year that this entry is for as YYYY.
monthList - List of month information, with one entry per month.
monthNameLong. E.g. January.
monthNameShort E.g. Jan.
monthNumber. E.g. 1
archiveLink. The link from the current page to the archive page for this month.
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:
date. This is a Date Object with a default format of "%a[LONG], %d[NP] %b[LONG] %Y".
posts. A list of Post Objects that were made during this day.
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:
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.
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.
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.
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).
id. This is only available if the weblog-tag-prefix configuration property is set. Used to uniquely identify this post.
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.
Option | Value |
|---|---|
hostname | Required. The hostname of the server where this feed is hosted. This is required so that absolute links can be created to individual posts. |
header weblog-image-url | Required. The URL of an image for this weblog. |
header weblog-description | Required. A brief description of the weblog. |
weblog-day-template | Required. This is required to build valid links to the articles in the feed. |
header author | Optional. Used to form the copyright notice. |
header language | Optional. The ISO language code, defaults to 'en'. |
For the RSS template to produce valid output the following options need to be specified in a template directive:
Option | Value |
|---|---|
output-type PlainText | Required. This ensures that articles are stripped of HTML before being placed in the RSS feed. |
character-set utf-8 | Optional. Some RSS readers do not support the default character set of ISO-8859-1, recommended to be set to UTF-8. |
plaintext-maxsize 197 | Required. RSS specifies a maximum size for article content. |
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.
Option | Value |
|---|---|
hostname | Required. The hostname of the server where this feed is hosted. This is required so that absolute links can be created to individual posts. |
weblog-day-template | Required. This is required to build valid links to the articles in the feed. |
weblog-tag-prefix | Required. Atom requires a unique, never changing ID for each post. PubTal forms this by creating a 'tag:' URI using the prefix and the date/time of the post. The prefix should be unique for each weblog and should not change, even if the name or location of the weblog changes. Suggested value: Once the value is defined for a weblog it should never be changed. |
header author | Optional. Used to form the author element, Anonymous otherwise. |
header language | Optional. The ISO language code, defaults to 'en'. |
For the Atom template to produce valid output the following options need to be specified in a template directive:
Option | Value |
|---|---|
output-type PlainText | Required. This ensures that articles are stripped of HTML before being placed in the feed. To place HTML into the Atom feed the template needs to be edited first. |
character-set utf-8 | Optional. Some RSS readers do not support the default character set of ISO-8859-1, recommended to be set to UTF-8. |
plaintext-maxsize 197 | Required. The Atom template is designed to contain a summary of the post, rather than a full post. |
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:
Option | Value |
|---|---|
weblog-suppress-monthly-rebuild | If this is set to False (the default), and the weblog-month-template is defined, then all pages generated by this template (day or month) will be rebuilt for the first post of a month. If the day template does not use the Monthly Archive object then set this to True to avoid rebuilding all pages at the start of each month. |
PubTal Version 3.5