Thalassa CMS logo

Thalassa CMS

What objects Thalassa is able to generate


Generated files, existing files and aliases

A web site generated with Thalassa CMS is almost entirely static (it can even be fully static if you don't use interactive features), and a static web site is essentially a directory tree with files. Some of these files are text, primarily the web pages themselves, represented with HTML; but your site can contain (and serve upon requests via the HTTP(S) protocol) binary files as well, and most of existing sites contain at least images (photos, pictograms and the like) represented as binaries.

The thalassa program can basically do three kind of things:

For publishing existing files, not too many variants exist: you can instruct thalassa to publish a single file (this is called binary, but certainly you can publish a text file this way as well) or to publish an entire directory (a collection). For a “collection”, you can choose to publish subdirectories recursively or to ignore them, to follow symlinks, ignore symlinks or make exactly the same symlinks, to ignore “hidden” files (that is, files with names starting with a dot “.”) or to publish them as well. Actually, it doesn't seem a lot of other things can be invented for the purpose of verbatim publishing (use the link to learn more).

For text files' generation, there are a lot of different features, and it's clear why: actually, that's what thalassa is made for.

Stand-alone HTML pages and other text files

The simplest thing you can do is just to generate a single stand-alone HTML page, or even an arbitrary text file. BTW, we actively “abuse” this feature to generate these .htaccess files for Apache; sometimes we even generate configuration files for the thalcgi.cgi program. Also it is relatively easy to make an RSS feed (which is technically just an XML file) with what Thalassa is capable of, and the stand-alone page facility fits this need the best.

A page (or, generally, a file) to generate may be entirely defined by a single [page] section in ini files, or you can create a [template] section and then let several [page] sections use it. The detailed description is found on the page devoted to creating simple pages.

Besides that, thalassa features generation of arbitrary text files outside of your web tree. This may be useful, e.g., to create configuration files for some third-party software, using options and other values defined in your ini files written for thalassa. This feature is called genfile (for generic file), and is configured with a [genfile] section. See the generic files page for the description.

Page sets

A more advanced approach to HTML pages generation is so called page sets. In your source tree, a page set is essentially a directory containing one object per each page you want to generate; the object may be either a text file in the headed text format, or a directory containing such a file (in this case, additional files, like images, may be added). Within ini files, a set is defined by a [pageset] section; to add more pages, you just place more files or directories into the set source directory, and on the next run of the generator they all become pages of your site.

It is useful to remember that sets as such are unordered. From the other hand, a set can serve as a source for a so-called list, or even for several lists.


The lists are perhaps the hardest-to-explain concept behind Thalassa, but they are extremely useful and, surprisingly, are in fact quite easy to use, once you understood what they are.

To start the explanation, let's say that a list is, well, a list — an ordered list of items. Every item may (but not necessarily do) correspond to a page to be generated; if this is the case, adding another item to your list causes thalassa to generate one more HTML file, called list item page (not to be confused with list pages). The list item itself (in contrary to the item page) is (intended to be) a relatively small piece of text, usually HTML.

List items (again, not to be confused with list item pages) can be put together in either direct or reverse order, thus forming, well, the list as such. You can choose to generate a single list page (and once again, not to be confused with list item pages), or an array of list pages, having your choosen amount of items per page. Furthermore, you can mark the list as embedded; in this case no list pages will be generated at all, and the list itself will be available wherever you want via a macro call.

If you need to understand better what is this all about, imagine a classic blog (not a microblog, it's important) or a news line. Every item, be it a blog entry or a news article, is represented both as its own page and as a short summary made for inclusion in various lists so that people can take a look and find the items interesting for them. These lists often tend to grow rapidly so a clear need arises to break the single very long list down to pages, showing a certain amount (say, 20 or the like) items per page. Such a blog or a news line is exactly what Thalassa lists are designed for (but they can be used for other purposes as well).

A list is defined by a [list ] section in the ini files, but this is only the very beginning of the story, because such a section only defines the list as a whole object, and one needs some way to define the items as well. In the present version, there are two possibilities.

First, you can introduce your own section group in your ini files for this purpose; for example, if you want to create a blog, the word blog may serve as a good name for such a section group, so individual entries in your blog will be defined by sections whose headers have the form [blog ENTRY_ID], like [blog 20230207_my_birthday], [blog 20230401_fools] etc; well, actually you can have any IDs you want, and they will turn into file names, like 20230207_my_birthday.html, 20230401_fools.html and so on.

The second possibility is that you can use an existing page set, or any subset of it, as the source for your list; actually one page set can serve as a source for several different lists. Page sets are by their nature unordered, so using them as list sources involves additional files that explicitly enumerate page set items to be included into a particular list, in the order they should appear in the list.

Besides the main intended use (for blogs, news lines and other similar things), lists can be conveniently used for some other purposes. For instance, if you need to create some similar pages, but don't want to have a separate file for each of them (or, may be, you just want to use Thalassa macroprocessor in their source texts, which is impossible within headed text files used for page sets), you can use for this purpose a list with ini file sections as its source. List item pages will serve your need, while the list itself in this case is most probably unneeded. To suppress generation of the list pages (you don't confuse them with list item pages, do you?), the list may be declared “embedded”.

In contrast, lists that use page sets as their item sources usually don't have item pages, because pages are in fact already there — they get generated as pages of the page set. So, likely for such a list you'll need only the list itself, not item pages. However, Thalassa list facility allows even this: you can instruct it to generate for your list its own item pages, which may look different from those generated for the set.

One more interesting thing about lists is that a single source can serve more than one lists. For example, if you have a news line on your site, but it has its own page, not the main page of your site, then you might want to have something like “last news” list on the main page. This can be done easily just by creating another list on the same source as your news. And one more list for the same source can be used to generate an RSS feed (which is technically just an XML file) for your news.

As usual, see the page devoted to lists for more information.


If you don't need these bloody aliases, you can easily skip this section. This must be true if you are going to create a new site from scratch; we strongly recommend not to involve any aliases until you absolutely have to.

Aliases are used when a single HTML page (or other object served via HTTP(S) from your site) for any reason should be accessible with more than one local URI. For example, suppose you have a real (that is, existing) file named foo/drink/drive.html within your web tree, so it has a full URL like, and (for any reason we don't want to know) you want it also to be accessible as foo/smoke/fly.html, which means the full URL should return the same content.

For a static site there are basically two approaches to achieve this. The simpler one is just to create foo/smoke directory and put there the appropriate symbolic link, which for this example would be named fly.html and must point to ../drink/drive.html.

This is exactly what Thalassa CMS aliases do. Objects configured for this purpose are known as “alias groups”; you can have several of them, although more than one is rarely needed. An alias group is defined by an [aliases ID] section in your ini files. In the simplest case, such a section will have just one parameter, which is also named aliases and contains a list of pairs <alias + original>. For every pair, Thalassa will compute the shortest possible symbolic link and create it.

Unfortunately, sometimes this is not sufficient to do what you need, specially when you're moving an existing and well-established site from a “traditional” CMS like Drupal or Joomla, and want to keep all your URIs working so that no links on third party sites get broken. Such sites are usually served in a fully-dynamic manner, which effectively means you don't have any real files nor directories there, hence your visible URIs are not bound by any filesystem-related reality. When there are no bounds, the so-called “webmasters” often create URI trees very difficult to reproduce with a filesystem path tree.

Suppose you need foo/smoke/fly.html to point to one (real) document, and foo/smoke to point to another one.

Well, do your best to avoid such nonsense as long as you can.

However, if you really have no other choice, then the second approach to aliases has to be involved, and it is to instruct your HTTP server (e.g. Apache) to do some alchemy on URIs before actually serving the request.

It is possible to put an .htaccess file into your web root directory and place there as many RewriteRules as you need to fully match what is needed. Well, you can even generate this .htaccess file as a stand-alone page, but Thalassa will not help you to generate the appropriate “rules”, you'll have to do it on your own. But you can end up with such an amount of “rules” that you'll have to decide this is not the way to go.

What Thalassa can actually help is to try hybrid approach, using symbolic links as mush as possible and only leaving unresolvable cases to your HTTP server. In the example above, you can still add two pairs to your list of aliases:


— but, knowing perfectly this can't work, you can in the same [aliases ] section specify explicitly that foo/smoke contains other links and hence has to be a real directory, not a symbolic link. After that you can also instruct Thalassa to generate a file inside each of such directories, set the name for the file, and specify a template for its content, where a local macro will be substituted with the target URI (taken from the list). Most probably the name will be .htaccess, and the file will contain the appropriate redirect directive.

Detailed instructions are found at the page devoted to aliases. If you really need them, well, we wish you good luck.

Additional objects

Additional objects are something which is not generated as separate files within your site's tree; instead, they are certain pieces of HTML code inserted here and there in your generated files.

Of what we have discussed already, embedded lists make a good example of additional objects. Besides that, Thalassa supports blocks, menus, index bars and user comment sections.

Block is simply an HTML code snippet; it doesn't even have to look like a “block”; in most cases it does, but generally it may be anything you want. Every block belongs to a block group, and each block group is a thing accessible via a macro call. The idea behind a block group is to represent something you want to appear on all (or many) of your pages, like a side panel, bottom or even something within or near the header of every page. Each block may have an associated tag, and the macro which generates a block group accepts an additional argument, allowing to pass a list of tags; a particular block will appear on the particular page (within the group) either if the block has no tag (which effectively means “show me everywhere”), or its tag is found in the set passed to the macro, or among the tags the page itself has. See the blocks and block groups page for more info.

Menu is effectively a list of links you want to appear in more than one place of your site (up to the case of every page). This could be achieved by already existing instruments, e.g., embedded lists, blocks or even simply html snippets, but there's one property specific for menus: if a menu is displayed on a page to which one of its items points, that particular item should be displayed differently (e.g., “disabled”). Menus provided by Thalassa involve associating a label with every menu item, and the macro, which generates the menu, also accepts a label as its argument; if the label matches, the corresponding menu item is displayed using alternative template. More information, including detailed instructions, is provided at the page devoted to menus.

Index bars are used for arrays of pages, which means there are several automatically generated pages, ordered and, more importantly, numbered. In the present version of Thalassa, there are exactly two cases of such arrays:

Appearance of index bars is configurable, and the result if available by calling a macro. For details, see the page devoted to index bars.

The last type of an “additional object” is a user comment section. Only list item pages and page set items may have comments; stand-alone pages in the present version of Thalassa are not suitable for publishing comments. In contrast with all the other types of additional objects, comment sections are not available through macro calls; instead, templates for pages suitable for comments are broken down to two parts, first for the page itself, and the second for the “page tail”; the comment section, if it exists, is placed between the page segments expanded from those template parts. Additional pages (with the same content, but containing other portions of the comments) are generated automatically, as appropriate.

Comments are configured by comment style ini file sections; page lists and page sets support configurable parameters to reference one of the existing configured styles and to set some additional options. Detailed description is on the page devoted to comment sections.

© Andrey V. Stolyarov, 2023, 2024