Configuration of PubTal

Documentation of PubTal configuration options.

All configuration is held in a single file, with all directory and file references relative to the directory containing the configuration file.  For example, if you have a configuration file new-site/site.config such as:

content-dir src

then the content will reside in the directory new-site/src/.

Three different configuration directives are supported:

  • Content - Configuration options set under this directive apply to the content of the website.
  • Template - Configuration options set under this directive apply to the templates used in the website.
  • SiteConfig - Global configuration options are set under this directive.
    • Upload - Several of these directives can be present under the SiteConfig directive.


If used, this directive must be the first directive in the configuration file.  It controls site-wide configuration.

content-dir dir

Sets the location of the content directory to dir.  Defaults to "content".

dest-dir dir

Sets the location of the destination directory to dir.  Defaults to "dest".

template-dir dir

Sets the location of the template and macro directory to dir.  Defaults to "template".

ignore-filter regex

Adds a regular expression to the filter list of files to ignore when looking for content to publish and upload.  For example, to ignore CVS and backup files (.txt~), add the lines:
ignore-filter .*?CVS.*
ignore-filter .*~$

character-set encoding

Sets the default character set that will be used for all templates and content across the site (can be overridden by the Content and Template directives).  Defaults to ISO-8859-15.

additional-plugins-dir dir

Adds an additional directory to be searched for PubTal plugins.

pubtal-data-dir dir

Sets the name of the directory that PubTal uses to store site information.  This directory is used internally by PubTal to store the state of the site, and so determines which (if any) files need to be uploaded.  Defaults to PubTalData.


Several Upload directives can be nested inside the <SiteConfig> directive.  They specify an upload destination which PubTal can upload content to.  An example of two different upload destinations is:

  host localhost
  username user
  host remotehost
  username remoteuser

The following Upload options are available:

method methodname

The upload method to use, defaults to FTP.

host hostname

Specifies the hostname of the upload location.

username username

The username to use when logging into the FTP site.

password password

The password for the FTP site.  This is optional; the command will prompt for the password if it is not specified in the configuration file.

base-dir dir

The directory that the website should be placed into on the FTP site (e.g. public_html).  Defaults to empty.

<Content [directory][file][*.file-extension]>

The Content directive controls default name-value pairs, the template to use when expanding content, and many other options.  See the later discussion on directive parameters for details of how multiple Content directives interact.

content-type type

Specifies that the content should be treated as being of this type.  Here is the list of content types supported by default, although additional content types can be added using plugins:
  • HTMLText
  • OpenOffice
  • Catalogue
  • Raw
  • Binary
  • Weblog

class classname

Specifies that this content belongs to a Class called classname.  All content is by default in the "normal" class, and by default the command will build only content that is part of the "normal" class.  By using the --class option however, a user can specify a list of classes that should be built instead.  Additionally the --all option can be used to build all content regardless of the class that it belongs to.

template templateFile

Set the template (relative to the template directory) that should be used for this content.  Defaults to template.html.

macro name templateFile

Adds templateFile to the list of macros that will be available.  All macros defined in the templateFile will be available to the template used when building the pages for this content.  Macros are available under the TAL path macros/name/macro-name. 

header name value

Adds a default value to the header name.  Can be overridden by the name-value pairs set in the content.

character-set charset

Sets the character set that this content is stored in.

preserve-html-spaces true | false

Set to false to disable the output of &nbsp; codes, which are used to preserve multiple spaces in content.  Defaults to true.

url-prefix http://domain-name

When set this will make the "absoluteDestinationURL" property available within the template.

htmltext-ignorenewlines true | false

Only applies to HTMLText.  Set to true to disable the output of <br> tags for newlines in HTMLText content.  Defaults to false.

catalogue-index-template templateFile

Set the template (relative to the template directory) that should be used for Catalogue master index pages beneath this directory.  Defaults to template.html.

catalogue-item-template templateFile

Set the template (relative to the template directory) that should be used for Catalogue item pages beneath this directory.  Defaults to template.html.

catalogue-max-columns number

Set the maximum number of items to put in a row before starting a new row when populating the catalogue/rows property.  Defaults to 5.

catalogue-build-pages [item],[index]

Control whether item, master index pages, or both should be built for Catalogue content.  Defaults to item,index.

catalogue-item-content-type type

Specifies the content type of the items listed in the affected catalogue(s), or disables treating the entries as content if set to "None" (the default).  If a catalogue has catalogue-item-content-type set to anything other than None, it will build individual entry pages using the "page" property which comes from treating the file specified by "filename" as being a piece of content of type type.

<Template [directory][file][*.file-extension]>

The Template directive controls the output type (HTML or XHTML), the character set of the template, and other options.  See the later discussion on directive parameters for details of how multiple Template directives interact.

output-type type

Specifies that the template is expecting content to be of a particular type.  Recognised types are:
  • HTML
Defaults to HTML.

character-set charset

The template is encoded in the given character set.

suppress-xmldecl true | false

Only applies to XHTML templates.  When set to true, the XML Declaration will be suppressed in the resulting file, useful for IE 6.  Defaults to false.

xml-doctype doctype

Only applies to XHTML templates.  If pyXML is installed then PubTal will use this to determine the DOCTYPE for the XHTML page.  If pyXML is not installed then this option should be used to set the DOCTYPE.  No default.

Directive Parameters

Both the Content and Template directives take optional parameters.  These parameters are (listed lowest priority first):

  1. A file pattern, e.g. *.txt
  2. A directory, e.g. test/
  3. A particular file, e.g. test/example.txt

If no parameters are specified then the directive applies to the root directory (i.e. the content-dir or the template-dir depending on the directive type).

If multiple directives apply to the same content or template then they are all used.  If the same option is set multiple times then the parameter with the higher priority takes precedence.  Take for example the configuration snippet:

header author Author One

<Content test/>
header author Author Two

<Content test/example.txt>
header author Author Three

The content file test/example.txt will have the name-value pair "author" set to "Author Three".  Any other content in the test/ directory will have the name-value pair set to "Author Two", and all other content in the site will have the name-value pair set to "Author One".

When parameters are set on a directory they are inherited by all the sub-directories as well.  For example content in test/subdir/ will also have the name-value pair "author" set to "Author Two".

If an option is set on a directory, and also set on one of its sub-directories, then content in the sub-directory uses the configuration setting of the deeper option.

File patterns can be targetted at a specfic directory.  Take for example a configuration of:

<Content test/*.txt>
header subject Text File

This will apply the name-value header "subject" to all files ending in .txt within the test/ directory, and all sub-directories (e.g. test/subdir/one.txt).

Last Modified: Sat, 07 Feb 2015 12:35:15 GMT

Made with PubTal 3.5

Copyright 2017 Colin Stewart

Email: colin at