Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
640 lines (377 sloc) 17.5 KB
---
title: Meta Information Reference
meta:
description: List and detailed information about all meta information keys that are used in one
way or another but the built-in webgen extensions.
---
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][path handler meta_info].
{:.important}
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][YAML] and needs to include the time part.
{:.information}
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][path handler meta_info].
{:.important}
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][path handler meta_info].
{:.important}
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!
[IO.new]: http://ruby-doc.org/core/IO.html#method-c-new
> 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][path handler meta_info].
{:.important}
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](../manual.html) for more
> information.
{:.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.
[link types]: http://www.w3.org/TR/html401/types.html#type-links
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.
{:.information}
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][proxy_path meta information] 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](../manual.html) for more
> information.
{:.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