Metadata

Overview

Metadata consists of auxiliary properties set on documents and directories, used in a wide variety of ways to enhance the presentation of the site's content. The titles and dates of articles, abstract/summary/description, keywords/tags, and other things of that sort are all common forms of metadata. Metadata is used to build indexes and feeds, and also in some specialized ways to control URL mapping and document presentation.

Most popular content managers use a database to store metadata, and often a database to store content as well. Since Bowfin is aimed toward working with content stored in an ordinary filesystem and/or version control system like a git repository, the database approach for metadata is problematic. Not only do databases require specialized tools for editing, but synchronization between content and metadata would make for a very fragile system. The extra work involved in maintaining a database for the metadata would annihilate the convenience of using the filesystem for content. We put careful thought into alternative systems for storing metadata, and came up with some ways that work more seemlessly with Bowfin's filesystem approach to content. A variety of different ways of storing metadata are provided, giving the user the freedom to choose the most sensible and convenient method for the task at hand. The different ways are:

embedded

Most common metadata properties can be stored right in documents themselves. We call this embedded metadata. Embedded metadata can be in a header, or parsed right out of the document content, like for example, the document title.

*.meta files

For file types where embedded metadata is impractical or undesired, a *.meta file can be used. These files live in the same directory as the file they refer to, and have the same basename, but with the extension ".meta". Note that for this reason, filenames in a content tree should be uniquified on the basename, i.e., do not have two documents whose filenames differ only by extension; extensions are effectively dropped when Bowfin builds its content index. The contents of a meta file are a single alist, which is a form following a pattern like this:

((KEY1 . VALUE1)
 (KEY2 . VALUE2)
 ...
 (KEYn . VALUEn))

filename-encoded

A limited subset of metadata properties can be encoded directly into filenames and paths. Bowfin can be programmed to parse information like dates right out of the filename — ultra-convenient for blogging. Refer to the documentation of the metadata property translate-paths below for details on how to use this.

_meta files

Metadata can be set on directories and their contents via a file called "_meta" that lives in the directory that it is about. The contents of this file should be a sequence of directory metadata and descendant metadata structures.

application-provided

There are times when you want to add metadata to a file or directory, but it makes more sense for the metadata to be stored in the website application than for it to be stored on disk alongside the content. Application-provided metadata fulfills this purpose, as well as the purpose of automatically-generated metadata.

Application-provided metadata is given as an argument to the backend constructor (keyword 'meta), and is essentially of the same form as descendant metadata. Strings and regular expression patterns are matched against the "on disk" paths of files in the backend. Currently, you can only add metadata to files by this method, not directories.

Supported Metadata Properties

Although you can add any property you like to your content, and add support for it to your application, some metadata properties are supported directly by Bowfin. You can use these metadata properties to access special features of Bowfin, and you should also avoid clashing names with them for your own invented features. We also list metadata properties that, while not supported specifically by Bowfin, in the sense of having these names hardcoded into the program, have names that we use by convention for specific purposes. Specific support for these names may be coded into Bowfin in the future. At the very least, users will find it most convenient to use these properties for their conventional purposes, as listed here.

date

Document publication date.

Stored internally as a srfi-19 date object.

Note: haven't decided yet on date format/datatype for use in metadata files. Use filename-encoded metadata to store dates for now, if possible.

description

String.

Abstract, summary, or description of a document, directory, or resource. Used in indexes and feeds.

noindex

(conventional)

Boolean.

When #t, advise application to not include this document in directory listings.

note: still thinking on whether this is the best way to do this. Users might sometimes want a document listed in some indexes, but not others.

regexp

Reserved for use with descendant-metadata system. Do not use for metadata properties.

short-title

String.

Short-title is used in certain directory listings where space is at a premium, like in a sidebar. It defaults to the resource's basename.

title

String.

Document title, for use in indexes and feeds.

translate-paths

This is a property for mapping urls to backend content. It is also the mechanism by which filename-encoded metadata works. It may be used in directory _meta files or in application-provided metadata only.

The value of translate-paths is a list of translations, (RULE ...) where each RULE is a cons, (PATTERN . TRANSLATION). Here is an example where we supply one rule. It translates a backend path like "2013/20130929–hello-world" to an URL path like "2013/09/29/hello-world" (file extension has already been dropped at this point). It also collects and stores the date and short-title of the document as filename-encoded metadata.

(translate-paths .
 ([(Y / Y m d "--" short-title) . (Y / m / d / short-title)]))

The following special patterns are available. All except for slash (/) collect metadata. Y, m, and d get normalized to the metadata property date.