Quick Start Guide for PubTal

An introduction to how PubTal works.

PubTal takes content files (e.g. text files), one or more template files (containing the website's look and feel), and produces corresponding HTML/XHTML files. Several different content formats are supported by default, and more can be added through a plugin mechanism.

This quick start guide is based on the HTMLText content type which is written in plain text with a limited amount of HTML markup. Each HTMLText file can contain (optional) name-value pairs at the start of the file, followed by a blank line, and the body of the page. The body text will have paragraph tags (<p>) and newline tags (<br>) automatically added to it, while additional markup can be included using ordinary HTML such as <b> tags for bold, and <a> for links.

PubTal templates are written as normal HTML/XHTML pages, but with TAL commands added in that tell PubTal where to place content in the generated page. TAL is a simple template language consisting of just 7 commands, and can be easily learnt from the examples. More information on writing PubTal templates can be found in the guide to Writing Templates.

Here is a simple example of how you can use the most basic features of PubTal. The directory layout for this example site is:

simplesite/site.conf
simplesite/content/index.txt
simplesite/template/template.html
simplesite/dest/index.html

The site.conf file will be empty because this example uses the default configuration. The file "simplesite/dest/index.html" file is generated by PubTal when we run the following command:

updateSite.py simplesite/site.conf

The file 'simplesite/content/index.txt' has the following content, in which a name-value pair of "title" is defined, and two HTML paragraphs are created:

title: My first page.

This is the first paragraph.
And this is a new line in the first paragraph.

The second paragraph shows <b>bold</b> and a <a href="http://www.owlfish.com/">link</a>

The file 'simplesite/template/template.html' is an example PubTal template containing TAL commands that position the content within the HTML page:

<html>
<body>
  <h1 tal:content="page/headers/title">Title</h1>
  <div tal:content="structure page/content">Body</div>
  <p>Last modified: <b tal:replace="page/lastModifiedDate">Date</b></p>
</body>

The contents of the H1 heading will be the title taken from the 'title:' line of the text file, with the main content appearing in the DIV element. The name-value 'title' is just an example; multiple name-values can be used and referenced in the template in the same way as 'title'. This is the resulting HTML file.

By separating content from HTML templates in this fashion, adding and maintaining web pages becomes very easy. To change the design of the website simply modify the template and then regenerate the pages with a single command. Different templates can be used in different parts of the site, with common parts shared between them. Default name-value pairs (accessed through the "page/headers/name" TAL path) can be set, and all configuration is inherited down through the directory structure.

To make learning PubTal easier there are several examples included with the download. The easiest one to start with is in the 'examples/homepage' directory, which provides a simple example of how to use a PubTal template to build site navigation links.

Plugins

Plugins can be used to add support for additional content types. Several plugins are installed by default, and the content types that they provide are described on the Content Types page.

In addition to the default plugins there is an additional plugin included with PubTal in the 'plugins' directory:

If you are interested in writing additional plugins please refer to the Plugin API page.

PubTal Version 2.0