Meta Information Reference

Following is a list of all the meta information items that are used in one way or another by an extension, be it a path handler, a tag or any other extension.

Meta information keys can either be set on source paths before nodes are created from them, or on nodes after node creation. For most meta information keys it doesn’t matter but some need to be set on source paths because they are used during the node creation. If the latter is the case, it is noted in the description.

For each meta information key a short description is given, followed by the syntax with an example and the paths/nodes for which this key is useful.

author

Specifies the author of the node.

This information is used, for example, by the path handler feed to include ownership information in the feed.

Syntax
String: Thomas Leitner
Paths/Nodes
Any

author_url

Specifies the homepage of the author of the node.

This information is used, for example, by the path handler feed and is normally only used when the  author meta information is also set.

Syntax
String: http://webgen.gettalong.org
Paths/Nodes
Any where the  author meta information is also set

blocks

Specifies options for content blocks of nodes in Webgen Page Format.

The special key “defaults” can be used to set default options for all blocks. Specific options for a block can be set by using the block’s name as key.

Syntax
Hash of Hashes: {defaults: {pipeline: erb,kramdown}, sidebar: {pipeline: erb}}
Paths/Nodes
Any in Webgen Page Format

change_freq

Specifies the change frequency of the page.

This information is used, for example, by the path handler sitemap. The following values are allowed for this key: hourly, daily, weekly, monthly, yearly, never.

Syntax
String: hourly
Paths/Nodes
Any

cn

Overrides how the canonical name for a node gets generated.

The value for this key needs to be a string describing how components of the source path as well as  version meta information should be used to create the canonical name. If not set, the default of <basename>(-<version>)<ext> is used.

The default value should be okay for most uses. However, when the  dest_path meta information is changed from its default one probably also wants to set this meta information.

The expressions in angle brackets <...> are interpreted specially, see below. It is also possible to surround optional parts with parentheses (only useful when the optional part contains one of the special expressions). Everything else is used as is.

The following special expressions can be used (examples are given for the source path /mydir/subdir/sub/01_image.en.jpg):

<basename>
The basename of the path. Example: image.
<ext>
The extension of the path. Example: .jpg.

The leading dot is included.

<version>
The  version meta information of the path. Example: default.

Note that if the version is “default”, this expression evaluates to an empty string! So the default version of a node never has the version name in its cn.

This key has to be set before a node gets created. Setting this value is therefore only useful, for example, in the paths block of a meta information path.

Syntax
String: <basename>(-<version>)<ext>
Paths/Nodes
Any path

created_at

Specifies the time when the content of the node was created.

If possible, webgen tries to set this information automatically on source paths. However, it cannont automatically be derived for paths provided by source file_system, so this has to be set manually.

Note that the value needs to be a valid YAML timestamp and needs to include the time part.

Syntax
Timestamp: 2008-08-14 10:25:34 +02:00
Paths/Nodes
Any

dest_path

Specifies how the destination path for a node gets generated.

The value for this key needs to be a string describing how components of the source path should be used to create the destination path. If not set, the default value of <parent><basename>(-<version>)(.<lang>)<ext> is used which should be okay for most uses. However, when a page path is part of a blog, for example, one might to include the creation year, month and date in the destination path.

If this meta information is changed from the default, one might also want to change the  cn meta information so that the destination path and the canonical names are similar.

The expressions in angle brackets <...> are interpreted specially, see below. It is also possible to surround optional parts of a path with parentheses (only useful when the optional part contains one of the special expressions). Everything else is used as is.

There is one special case: If the value starts with webgen:/, the rest of the value is taken as it is as the destination path. This allows one to override the default mechanism.

The following special expressions can be used (examples are given for the source path /mydir/subdir/sub/01_image.en.jpg):

<parent>
The parent path. Example: /mydir/subdir/sub/.

This includes the trailing slash if the parent path is a directory.

<parentNUM>
NUM is a positive (starting from zero) or negative (counted from the back) number and specifies one part of the parent path.

Example: <parent0>mydir, <parent-1>sub, <parent1> = <parent-2>subdir

<parentNUM1..NUM2>
NUM1 and NUM2 are positive (starting from zero) or negative (counted from the back) numbers and specify a range of parts of the parent path which are separated by backslashes.

Example: <parent0..-1>mydir/subdir/sub, <parent1..-2>subdir

<basename>
The basename of the path. Example: image.
<ext>
The extension of the path. Example: .jpg.

The leading dot is included.

<lang>
The language of the path. Example: en.

Since only file paths can have a language part, this expression together with some static strings is normally surrounded by parentheses to avoid the use of the static strings when no language part is available.

The  path_handler.lang_code_in_dest_path configuration option can be used to specify when the language part should be used in the destination path.

<version>
The version of the path. Example: default.

Used like the <lang> part. The  path_handler.version_in_dest_path configuration option can be used to specify when the version part should be used in the destination path.

<year>, <month>, <day>
The creation year, month and day of the path. Example: 2013, 05, 05.

This key has to be set before a node gets created. Setting this value is therefore only useful, for example, in the paths block of a meta information path.

Syntax
String: <parent><basename>(-<version>)(.<lang>)<ext>
Paths/Nodes
Any path

draft

If this key is set on a source path, no node will be created from it.

This is used to add content to a website which should only be used later on.

Also see  no_output meta information.

Syntax
Boolean: true
Paths/Nodes
Any path

handler

Specifies the path handler that should be used for creating nodes from the path.

This key has to be set before a node gets created. Setting this value is therefore only useful, for example, in the paths block of a meta information path.

Syntax
String: copy
Paths/Nodes
Any path

io_open_mode

Specifies the IO mode that should be used for reading data from the path.

The default IO mode for reading the contents of a path is ‘r’ which means that the underlying IO object is read using the default system encoding. Some path handlers (like path handler copy) override this behavior if necessary.

Overriding the default IO modes is useful, for example, when certain paths need to be openend with a different encoding (e.g. ‘r:ISO-8859-1’) or to avoid problems with the Unicode byte order marker (e.g. ‘r:BOM|UTF-8’).

For detailed information on the allowed values see the IO.new documentation!

This key has to be set before a node gets created. Setting this value is therefore only useful, for example, in the paths block of a meta information path.

Syntax
String: r:bom|UTF-8
Paths/Nodes
Any path

lang

Sets the language for a file path.

The value has to be a valid ISO-639-1/2 character code for the language (e.g. ‘en’ for English or ‘de’ for German). Since only file paths can be localized this key is ignored for directory and fragment paths.

Note that this key needs to be set on a source path before a node gets created. It is not used by webgen if it set afterwards!

This value can also be encoded into the source path name. See the manual for more information.

Syntax
String: de
Paths/Nodes
Any file path

Specifies additional information, for example, about the position of the page regarding other pages. A sample usage would be to express that the page is logically followed or preceded by a certain page.

The value needs to be hash and its keys need to be link types except for the special javascript and css keys (which will be discussed below). The link type is used to specify the relation of the page to the linked path. The value can either be a string which is interpreted as a path to the internal or external file; or a hash with arbitrary key-value pairs (use lower case key names) but it should include at least a href key to specify the path to the internal or external file; or an array containing strings or hashes to specify more than one linked file for a given link type.

The special keys javascript and css may have an array of strings or a string as value which are interpreted as paths to javascript/CSS nodes that should be included in the generated page.

This information is used by the content processor html_head to insert the approriate tags in the head section of the generate HTML document.

Syntax
Hash: {next: next_doc.html, prev: prev_doc.html}
Paths/Nodes
Page paths/nodes

link_attrs

Specifies additional attribute-value pairs that should be added to a generated link to the node.

The special key ‘link_text’ can be used to specify the text that should be used as link text.

Syntax
Hash: {title: Hallo, class: extra, link_text: Used as link text}
Paths/Nodes
Any

meta

Specifies names and values for <meta> HTML tags.

These key-value pairs are properly escaped and inserted into the generated destination path by the content processor html_head.

Syntax
Hash: {author: Thomas Leitner, generator: My program}
Paths/Nodes
Page paths/nodes

modified_at

Specifies the time when the node was last modified.

This information is automatically set for paths provided by the source file_system (the file modification is used) but can be overridden by setting it manually.

Since this key is always needed by webgen, it is set to the time when webgen is executed if it does not not contain a valid timestamp value.

Note that the value needs to be a valid YAML and needs to include the time part.

Syntax
Timestamp: 2008-08-14 10:25:34 +02:00

Paths/Nodes * Any

no_output

Specifies whether the destination path for the node should be written or not.

This differs from the  draft meta information in that nodes for a source path that has this key set get created nonetheless. However, sometimes it is useful to have a node representation of a source path although it can not be output (e.g. for fragment nodes or nodes representing external links).

Syntax
Boolean: true
Paths/Nodes
Any

omit_dir_index

Controls whether a directory index path (see  proxy_path meta information) should appear in a breadcrumb trail generated by the tag breadcrumb_trail despite the setting of the  tag.breadcrumb_trail.omit_dir_index configuration option.

Syntax
Boolean: false
Paths/Nodes
Proxy nodes for directories

passive

Specifies whether this is a passive path/node or not.

Passive nodes are exactly the same as normal nodes except that they are only written to their destination path if they have been referenced.

Sytnax
Boolean: false
Paths/Nodes
Any

pipeline

Specifies the processing pipeline for paths handled by path handler copy.

Note that it makes a difference whether this key is set on a source path or only later on the created node. See path handler copy for the details.

Syntax
A string with content processor short names separated by commas: scss,rainpress
Paths/Nodes
Any that is handled by path handler copy

priority

Specifies the priority of the node in respect to all the other nodes of the website. This information is used, for example, by the path handler sitemap.

Syntax
Float: 0.5
Paths/Nodes
Any

proxy_path

Specifies the path to a proxy node to which all routing requests are forwarded.

This is very useful, for example, for directories because it allows one to specify a directory index path that is linked to instead of the plain directory itself.

Syntax
String describing an (a)(l)cn: myindex.html
Paths/Nodes
Any but most common for directory nodes

routed_title

Specifies the title to be used on generated links when the node is also used as proxy node.

For example, if this key is set on the proxy node for a directory, links to the directory get the routed title as link text.

Syntax
String: Image Directory
Paths/Nodes
Any

routing_path

Specifies the path that should be used when routing to a node.

The difference between the  proxy_path key and this key is that the proxy_path key needs to refer to an existing node whereas this can be any path.

This can be very useful, for example, when wants to have URLs without the .html extension:

website.blackboard.add_listener(:apply_meta_info_to_path) do |path|
  if path.ext == 'page' && path.to_s !~ /\/index.page$/
    path['dest_path'] = '<parent><basename>(-<version>)/index.(<lang>.)html'
  end
end

website.blackboard.add_listener(:after_node_created) do |node|
  node.meta_info['routing_path'] = node.dest_path.sub(/index.html$/, '') if node['handler'] == 'page'
end
Syntax
String describing an (a)(l)cn: myindex.html
Paths/Nodes
Any

sort_info

Specifies the sort information for a node.

Any string or integer value can be used here. When two nodes are compared using this information and both have integers, then an integer comparison is done. Otherwise a String comparison is done.

Setting a string value is useful, for example, for specifying dates as sort information.

This value can be encoded into the source path name. See the manual for more information.

Syntax
Integer or string: 15
Paths/Nodes
Any

template

Specifies the template that should be used for a page/template node. If set to null (i.e. ~), no template is used for the page/template node!

Syntax
String or null: my.template or ~
Paths/Nodes
Page/Template paths/nodes

title

Specifies the title for the node.

Syntax
String: New Title
Paths/Nodes
Any

translation_key

Specifies the translation key that should be used for the path/node.

All nodes with the same translation key are assumed to represent the same content but in different languages. The default translation key is the absolute canonical name.

Syntax:
String: some content specific string
Paths/Nodes
Any

write_order

A string used for determining the write order when writing nodes to their destination.

By default, this meta information key is not set and is therefore equal to the empty string.

Syntax
String: zzz
Path/Nodes
Any

version

Specifies the version name of a source path.

This key should be set on a source path before a node gets created because it is used in constructing the canonical names as well as the destination path.

If no version name is specified, the version name “default” is automatically used.

Syntax
String: small
Paths/Nodes
Any path

versions

Allows one to specify meta information keys for different versions of a source path.

This key needs to be set on a source path before nodes get created from it. Its value needs to be hash with version names as keys and meta information hashes as values.

For each version defined the source path is duplicated, the provided meta information keys as well as the version name are set on the duplicated path and only then is it given to a path handler.

Syntax
Hash of Hashes: {default: {title: Big Image, size: 1024x768}, thumb: {title: Thumbnail, size: 64x48}}
Paths/Nodes
Any path