Clone wiki

terbium / Documentation

Terbium Documentation

Installation instructions are maintained elsewhere. There are also QuickStart instructions for the simplest cases.

Overview

Terbium takes files and directory structure from a source location and builds a static HTML-based browseable target hierarchy.

The default configuration constructs an index.html for each directory in the source tree. This contains thumbnail images and links to detail pages on each sub-directory, file, and sym-link in the originating directory.

It also creates an HTML detail page for files in the source hierarchy. The name of the detail page file is the name of the original file with an "html" suffix. Thus orange.jpg has its details shown on orange.jpg.html.

By default, for every image file (.bmp, .jpg, .gif, .png), thumbnail and icon-sized images are generated (orange.thumb.jpg and orange.icon.jpg).

! Note The specific output for files can be altered through the terbium.json file but this is rarely needed.

Every file and directory in the source location may have additional meta-data specified in properties file. This is done for information such as "title", "subtitle" and for determining display order within the owning directory's index.html file.

! Note Terbium also has limited support for the <image>.xml and album.xml files generated by BINS. This capability is only intended for migration and is not documented.

On startup, Terbium requires basic configuration information. Three locations are checked for this information.

  1. a file named terbium.json in the terbium install directory (this may differ depending on distribution, but may be something like /usr/share/site-packages/terbium).
  2. a file named .terbium.json in the user's home directory.
  3. a file named terbium.json in the <source> directory.

The last one wins, so if both ~/.terbium.json and <source>/terbium.json define "site-copyright" only the <source>/terbium.json value is used.

The terbium.json file is a JSON file with many possible entries detailed separately.

Templates configuration

A template-specific configuration may exist. It is a typical JSON file, residing in <template-dir>/template.json. The usual intent for this file is to define colour schemes and asset files (Javascript or CSS files) that also need to be generated by Jinja (instead of copied as-is).

.properties Files

Directories, files and symlinks may have .properties files associated with them to provide additional meta-data. They are optional; you never need to create them if you do not want to.

For directories, the file is named album.properties. For files and symbolic links, the file is named by attaching the .properties suffix to the name of the file. For example the properties for the file orange.jpg would be maintained in orange.jpg.properties.

AlbumProperties and FileProperties are discussed separately for the commonly used default properties.

! Note Advanced users may customize which properties are available for display in their own templates. The AlbumProperties and FileProperties pages deal with the default templates and represent the normally-expected set of properties.

Fallback

Some properties are used internally by Terbium when asked to sort contents of a directory. When possible, if an overriding property is not defined in a .properties file, header information is used from the image. For example, if the "date" property is needed for a JPEG file, the <file>.properties are checked. If "date" is not defined, then the date embedded in the JPEG's EXIF header is used. If that is not available, then the date that the original JPEG file was last modified is used. Where this fall back occurs, it is noted in AlbumProperties and FileProperties descriptions.

On *nix-like file systems, symbolic links may be created within your source hierarchy to allow a file or directory to appear in multiple places without needing an actual copy of the file/directory.

Files

A file may be displayed at multiple locations in the target hierarchy without needing to copy the file into multiple places in the source hierarchy. This can be accomplished by creating a symbolic link in the location you want an additional copy to "appear". The file data, thumbnail and preview are only created once in the target, but multiple detail pages may be created, and the file will show up as just another file in the directory's index.html file.

ln -s ../../food/fruit/orange.jpg ./not-an-apple.jpg

In this case, orange.jpg in another directory will appear in the current (working directory). It has the default display name of "not-an-apple" and its details page would be named not-an-apple.jpg.html. Properties for its appearance in this directory would be contained in not-an-apple.jpg.properties. Properties not in this file (or if the file is missing) would be read from the ../../food/fruit/orange.jpg.properties file for the original image.

Absolute symlinks are allowed, but (as of the current release) only links to files that ultimate reside underneath the source directory are valid. Linking to a file outside the source directory will in errors.

Directories

While symbolically linked files appear as normal files in the directory's index.html page, when a directory is symbolically linked, it appears as a "related item". By default, these follow the file listing/thumbnails in the index.html page.

ln -s ../../food/fruit ./healthy-stuff

adds the thumbnail for the "fruit" directory in the current directory's index.html page as a related item, by default named "healthy-stuff". To override this or other properties for the link, use the healthy-stuff.properties file.

Shortcut files

These are like ''symbolic links'' discussed above, but intended for use in environments where symbolic links are impractical or unwise. To create a link similar to the symbolic link example above, you would create a not-an-apple.link file in the appropriate location. The .link file is a properties-style file with sections to override the linked item's [meta] information as will as provide details for the [link] itself. The contents for our example would be:

[meta]
title = Not An Apple
[link]
file = ../../food/fruit/orange.jpg

Sorting

With the default templates, thumbnails and links to sub-directories always appear first in the index.html page for a directory. This is followed by thumbnails/links for files in the directory (whether actual files or symbolic links). At the end, a section of "related" items consisting of thumbnails and links for any directories symbolically linked.

Each of these sections is sorted based on the properties of the items in it. The sort order used can be specified globally in a [[terbium.json]] file, or locally to a directory in its AlbumProperties file.

Construction of a sort order definition string is discussed in SortOrder.

Updated