title: Quick Start Guide for PubTal
subject: 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 <dfn>HTMLText</dfn> 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, which are then available for reference in the template.

The body of an HTMLText file is a mixture of normal text and HTML markup, such as &lt;b&gt; tags for bold, and &lt;a&gt; for links.  PubTal will automatically add paragraph tags (&lt;p&gt;) and newline tags (&lt;br&gt;) to the body text when generating the web page.

PubTal <dfn>templates</dfn> are written as normal HTML/XHTML pages, but with <dfn>TAL</dfn> 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 <a href="conf/templates.html">Template Basics</a> section of this manual.

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

<pre><code>simplesite/site.conf
simplesite/content/index.txt
simplesite/template/template.html
simplesite/dest/index.html
</code></pre>

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:

<pre><code>updateSite.py simplesite/site.conf</code></pre>

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:

<pre><code>title: My first page.

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

The second paragraph shows &lt;b&gt;bold&lt;/b&gt; and a &lt;a href="http://www.owlfish.com/"&gt;link&lt;/a&gt;.
</code></pre>

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

<pre><code>&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"&gt;
&lt;html&gt;
&lt;head&gt;
  &lt;title&gt;An Example&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
  &lt;h1 tal:content="page/headers/title"&gt;Title&lt;/h1&gt;
  &lt;div tal:content="structure page/content"&gt;Body&lt;/div&gt;
  &lt;p&gt;Last modified: &lt;b tal:replace="page/lastModifiedDate"&gt;Date&lt;/b&gt;&lt;/p&gt;
&lt;/body&gt;
</code></pre>

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 <a href="example/index.html">resulting HTML file</a>. 

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 the single command updateSite.py.  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.
