Wagtail Configuration

Wagtail is controlled by (too many) configuration files. These config files are read from two places. Firstly, the files in /etc/wagtail/ are read and then the files in $HOME/.wagtail/. The 2nd set of files are merged in, with key/value pairs from the first set of files being overwritten where there are clashes.

Configuration files consists of a number of key/value pairs in the form of key=value. Sections in the configuration file are denoted by a section header in the form of [name]. Pairs appearing before the first section header are said to exist in the 'global' section.

The following is an example configuration file:

A line which starts with a hash (#) or semi-colon is treated as a comment and is ignored.

Any directories specified in a configuration file must include the trailing slash. So /I/live/here/ is right whilst /I/live/here is wrong.

In various places in the config files variables are available to be used. These take the form of %SOMETHING%. These variables will be replaced by the appropriate value when needed. The exact variable names available at any one time varies. In Wagtail 0.1 variable names were upper-case only, this is no longer true and variable names are case-insensitive.

When variables are used in forming commands you should place double-quotes around them were appropriate, e.g. somecommand "%TITLE%". The variables used for file-names (%IN%, %OUT% and %FILE%) are quoted automatically if you omit quotes. However, you can still say: cp %FILE% "new_%FILE%" should you want to.

Any variable name that ends with _THE will be processed so that "The Word" would become "Word, The".

Starting with Wagtail 0.2 values from loaded configuration files can be accessed with the form %CONFIG/file/section/key%. Don't forget the final percent symbol. To access keys in the global section leave the section field blank.

Variables appearing in referenced configuration keys are evaluated. So, yes, you can set up infinite loops.

If a variable is used which isn't defined, it will take the value "[unknown]".

Wagtail 0.4 introduced support for multiple options in configuration files. This means that more than one entry in a configuration file can have the same key. For example:

If the part of Wagtail reading the configuration file isn't expecting multiple options, the first entry is used. However, if multiple options are expected than the best matching option is chosen.

'Best matching' is defined as the key which has the lowest number of undefined variables. If two or more have the same lowest value then the first option is chosen. In the example above the artist key will store the contents of the ARTIST variable if it is defined. If not, the DISC-ARTIST variable is used instead, if it is defined. If neither is defined the value is set to "Unknown artist".

If Wagtail is searching for a best match and encounters a %CONFIG...% variable, the config search is also conducted in a best match manner. So, continuing the example above saying %CONFIG/(file)/somesection/artist% would search for the best match as before.