First of all, let us repeat the warning we already gave: don't use the aliases feature until you're absolutely forced to. For instance, if you're working on a brand new site, you shouldn't need aliases, and if you think you do, chances are you're doing something terribly wrong.

If you decide to continue reading this page, be sure to read the introduction first. Even if you already read it, it might be a good idea to refresh the impression.

Aliases are defined with ini file sections of the aliases group, e.g.

  [aliases main]

The particular section name (main in this example) play no real role, so you can pick an arbitrary identifier for this purpose. The only limitation is that in case you need more than one section in the aliases group (which is highly unlikely), you must choose distinct names for them.

The aliases as such must be listed in the aliases parameter. Its value is a text consisting of lines, one alias per line. Every line must consist of two strings, delimited with a colon “:”, the first string being the alias, and the second string being the original path. Both are relative to the site's tree root, and both must not have a leading “/”. Leading and trailing whitespace is stripped off; empty (and whitespace-only) lines are ignored; in the present version all lines that contain no colon are ignored as well, but this may change one day.

Thalassa does its best to make shortest possible symlinks, but always make them point to relative paths; it also makes directories as necessary. For example, if the following aliases are configured:

  [aliases main]
  aliases = foo/bar/bur.html    : site/node/burbur.html
            site/node/abra.html : site/node/cadabra.html
            foo/bar/star.html   : foo/bur/foobar.html

then Thalassa will try to make directories foo, foo/bar and site/node (but it looks like it will only make the foo/bar as the other two are already there), and the following symlinks will be created: foo/bar/bur.html (to ../../site/node/burbur.html), site/node/abra.html (to cadabra.html) and foo/bar/star.html (to ../bur/foobar.html). Just like both Unix symlink syscall and link -s command, Thalassa does not check the target in any way, it just creates the requested symlinks, even if they become dangling.

In case you've got a lot of aliases, it might be a good idea to place them in a separate file and use smth. like this:

  [aliases main]
  aliases = %[readfile:aliases.lst]

Sometimes aliases may conflict, like this:

  [aliases main]
  aliases = foo/bar/bur.html : node/a.html
            foo/bar          : node/b.html

Thalassa does not (at least in the present version) try to solve such conflicts in any way, it just fails and reports an error; which of the aliases will fail depends on their order, i.e., in this example Thalassa will fail to create the foo/bar symlink because there is already a directory with that name, but if you swap the lines, then foo/bar/bur.html will fail because foo/bar already exists and is not a directory.

There is a way to solve such a situation, but the solution must be applied manually. First of all, use the force_dirs parameter in the same aliases section to supply Thalassa with names that must be handled as directories. The parameter's value is a comma-separated list of paths; leading and trailing whitespace for each list item is stripped. Every time Thalassa encounters an alias item whose name (the path to the left of the colon) is included into the force_dirs list, it makes the corresponding directory instead of creating a symlink; then, a text file is generated inside such a directory. The name of the file is set by the dir_file_name parameter, and the contents for the file is defined by the dir_file_template parameter, in which, besides all usual macros, a macro named %target% is supported; it is replaced with the target path of the alias being handled this way (the path to the right of the colon). Usually the file is named .htaccess, and its text consists of the appropriate RewriteRule directive; refer to the Apache documentation for details.