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:
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.
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))
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
below for details on how to use this.
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.
Directory metadata is given as a simple alist, like that described for *.meta files above, and these properties apply to the directory that the _meta file is in. If there is also an 'index' document in the directory, the directory metadata applies to that document as well.
Descendant metadata is a way for a directory _meta file to provide metadata for the directory's contents. It is given as a structure
(PATTERN . ALIST), where
ALISTis an alist of metadata as for directory metadata, and
PATTERNis a descendant matcher of one of the following types:
string: a literal content-entry path given as a string. A relative path to the content-entry to which to apply this metadata.
Pis a string regular expression or SRE, to be matched against relative paths.
Pattern matching is done against the relative pathname as it is "on disk", with file extension and prior to path translation.
Descendant metadata can apply only to files. Adding metadata to subdirectories by this method is not supported.
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
'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.
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.
Abstract, summary, or description of a document, directory, or resource. Used in indexes and feeds.
#t, advise application to not include this document in directory
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.
Reserved for use with descendant-metadata system. Do not use for metadata properties.
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.
Document title, for use in indexes and feeds.
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
_meta files or in application-provided metadata only.
The value of
translate-paths is a list of translations,
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
(translate-paths . ([(Y / Y m d "--" short-title) . (Y / m / d / short-title)]))
The following special patterns are available. All except for slash (
d get normalized to the metadata
- Y: four digits
- m: two digits
- d: two digits
- short-title: a sequence of any characters
- /: a path separator