System Variables

This chapter lists all variables interpreted or produced by FileWiki. Note that these variables are in capital letters, in order to distinguish them from the user-defined variables.

Configuration Variables

The variables described here directly affect the FileWiki behaviour.


Mandatory. Points to the top-level directory of the website. This must be set as function parameter to the FileWiki calls.


Target (output) directory of the website. Mandatory for the FileWiki::create() function. Absolute as well as relative paths are allowed.

NOTE: The given directory as well as all subdirectories will be created on the fly, without checking or user inerraction. Make sure to provide a reasonable value here.




Mandatory. Defines a list of plugins to be enabled. There are three types of plugins:

  • Page handler: Create a web page (e.g. Markdown, Copy, GenericPageHandler), or more generically spoken: Generates a target by transforming a source file. Only one page handler is allowed per source file. If no page handler plugin is enabled, the source file will not be processed.

  • Vars provider: Provide extra variables (e.g. Git, EXIF). Multiple vars provider are allowed.

  • Resource creator: Creates additional resources for a page (e.g. ImageMagick, ExtCmd). Multiple resiource creators are allowed.

Refer to FileWiki::Plugin::* modules documentation for further information about each plugin.



This enables the Markdown and Copy plugin.


Defines a match on file names for a plugin. The given plugin will be enabled if the file matches the expression.



This enables the "Markdown" plugin for all files ending with ".txt", and the "Copy" plugin for all files ending in ".ico" or ".png".


Defines a match on file names for a plugin group. The plugins in the given group will be enabled if the file matches the expression.


PLUGINS=EXIF<IMAGE>, ImageMagick<IMAGE>(THUMB), GenericPageHandler<IMAGE>

This assigns the EXIF (vars provider), ImageMagick (resource creator) and GenericPageHandler (page handler) plugins to the IMAGE group. All files ending in ".jpg" or ".png" will be processed by the plugins in the IMAGE group.


Mandatory. Template to be parsed for the page. Relative to TT_INCLUDE_PATH.


Set configuration options for Template Toolkit. See Template::Manual::Config for a complete list of options.

Make sure the INCLUDE_PATH points to your template directory.

For the FileWiki apache handler to work correctly, you also need to set ABSOLUTE=1.




Command being executed by FileWiki::command($command) function.


CMD_INSTALL=rsync -rvz --delete -e "ssh -l webmaster" ${OUTPUT_DIR}/

This installs the page to the host when typing:

filewiki -c install


Prefix for the URI's generated by FileWiki. Useful if the website generated is in a subdirectory within some other site.


Set the root URI to a new value. This will make the source directory (as well as all including files and folders recursively) appear under a new root URI.

NOTE: Set this in dir.vars. You will get unexpected result when set in tree.vars!


If set, convert all URI's to lowercase.


Format: "YYYY-MM-DD hh:mm:ss" or unix timestamp

If set, affects modification date for the target (output) file of a page.

This is particulary useful if you use rsync -t for installing the site, and you don't want a page's mtime to change on every install.


Defines how time is formatted in the system. They correspond to the C library routines "strftime" and "ctime". Defaults to "%C".



Result: "January 1, 2011"


If set in dir.vars or tree.vars, files as well as subdirectories will not be processed. If set in page.vars, the page will not be processed.


If set, the page will be excluded from the PAGE_PREV / PAGE_NEXT list (see below).


Specifies the order of the page within the current directory. Defaults to the source file name.

Important when creating menues using the PageTree() or PageList() functions in the templates.

Note that the index is being sorted lexically (NOT numerically): This means for example that "10" is considered smaller than "2". You should use "02" here.


Marks the page as INDEX_PAGE for the directory. This is mainly used by the menu.


Comma separated list of references to the page URI. Used by the HTML converter (Markdown or Textile) to create links from a reference.

Only useful in page.vars.


Key to use for sorting pages within a directory. Defaults to "INDEX".


Strategy to use for sorting pages within a directory. Supported values are:

  • sortkey-only: sort by SORT_KEY (default).
  • dir-first: sort by SORT_KEY, but put directories in front.
  • dir-last: sort by SORT_KEY, but push directories to back.
  • none: do not sort (useful when using INCLUDE).


Order to use for sorting pages within a directory. Supported values are:

  • asc: sort ascending (default).
  • desc: sort descending.


Include variables from a given vars file. Note that no checking on circular including is performed. Make sure that you don't include vars files which include the currently parsed file again!


Include files/directories. Multiple includes are separated by a colon, or by using array variables. Optionally, you can specify a prefix from where to read additional tree-, page- and file-vars in square brackets.

Example (include files):


This includes the file specified. The vars for the included file will be read from myprefix.vars in the current directory.

Example (include file and assign plugin):

INCLUDE=/my/special/script.js > JavaScript

This includes the file specified, and sets PLUGINS=JavaScript in page vars.

Example (include directories):


This includes the directories specified. The vars for the included directory will be read from myprefix.tree.vars and myprefix.dir.vars in the current directory. The vars from subdirectories will be read from myprefix_subdir.tree.vars and myprefix_subdir.dir.vars. The vars from a file myfile.txt within the directory will be read from myprefix_myfile.txt.vars.

Example (use array variable):


Same as above, using array variable notation.


Exclude files/directories on matching pattern. Multiple excludes are separated by a colon, or by using array variables. The match is done against the full path starting at BASEDIR.



The first example excludes any file or directory named "test.txt". The second example excludes any file or directory containing the word "private" (e.g. "somedir/private" or "my_privateer.txt"), and any file or directory ending with ".bak".


If set, force a rebuild of all resources (i.e. all files generated by resource creator plugins), even if the resource files already exist.


Modify source file data before it is processed by plugins. Use with care!

The only supported regexp modifier is 'g'. Note that filewiki always adds the 'm' and 'ee' modifiers.

Example (fix links in Markdown source):


Preset Variables

The variables described here are set by FileWiki, and can be used in the templates.


The name of the page (or directory respectively). This is taken from the filename. Changing this variable directly affects the URI variable (or URI_DIR for directories).


System environmnent (reference to Perl %ENV).


Modification date, taken from the source file modification date, and formatted using the TIME_FORMAT variable.


Date of the generation of a page. This is set to the systems current date upon page generation, and formatted using the TIME_FORMAT variable.


Points to the previous page in current directory. Not set if current page is first page.


Points to the next page in current directory. Not set if current page is last page.


Container for the dir.vars. Makes the dir.vars accessible from the page.

Template Example:

[% DIR.my_var %]

Returns the variable my_var from dir.vars.

Transformation Variables


EVAL variables must be declared as arrays (using the '+' modifier).

Expression of form [!]KEY: EXPR. Sets $_ to the value of KEY, and assigns the value of $_ to variable KEY after evaluating EXPR.

The transformation happens after "variable late expansion", or, if the ! modifier is set, before any variables are read from disk. Using the ! modifier makes only sense if you wish to transform system variable presets at an early state (e.g. NAME or URI_DIR).

Note that EXPR is evaluated using the perl eval statement, which means that you can do very nasty stuff with this!


+EVAL  !NAME: s/^\d+-//
+EVAL  NAME: WARN "EVAL: malformed NAME=$_" if($_ =~ /^[^A-Za-z]/)
+EVAL  title: s/_/ /g

The first line removes leading digits from variable NAME, affecting the resulting URI of all pages down the tree. The second line prints a warning if NAME does not start with a letter. The third line replaces all underscores with whitespace on variable title.

Invasive Examples:

+EVAL  NAME: print "I'm a dirty hacker! " while 1
+EVAL  passwd: $_ = `cat /etc/passwd`

These examples show why you should not let FileWiki process variables from unknown sources.