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>)(-<timestamp>)(.<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.

<modified_at>

The timestamp when the path was modified. Example: 20180506082015.

This part is non-empty if the [timestamp_in_dest_path meta information] is set and allows to include the modified_at meta information timestamp in the destination path which is useful for cache busting purposes.

<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

link

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_property

Specifies properties and values for <meta> HTML tags.

Similar to the meta key but uses property instead of name. 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

modified_at_in_dest_path

Specifies whether the modified_at meta information should be used when creating the destination path for a node. See the dest_path meta information for more information.

This key needs to be set on a source path before nodes get created from it.

Syntax: Boolean: false
Paths/Nodes: Any path

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.

Syntax: 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