Common metadata fields
The following metadata fields are nearly always used (this might depend on your template).
| date: | the modification date of the node. Set automatically to the mtime of the file. |
| export: | can be used in index.rdoc nodes to export fields to
"child" nodes (those in the same directory as the
"current" one and below). e.g.
export: toplink gentoc template plugins toptext footer |
| id: | used when linking. It defaults to the filename (without the trailing .rdoc), but you can add more IDs separated by spaces. You might want to add a WikiName if the filename is lowercase. |
| linklist: | can be specified in .inc (sidebar) files to append a list of links
to the contents of the body. Should consist of WikiNames, site:id or
[[site:id label]] links separated by spaces. Example:
linklist := site:command site:comment [[site:external A link to the external command node]] . |
| metaonly: | if set to yes, the node can only export metadata fields but it won’t be formatted (i.e. it won’t go through the plug-in chain specified in plugins, just export that field) |
| nowikinames: | if set to yes, WikiNames will not be resolved in the node even if a possible target exists, and you won’t get any warnings if it doesn’t. |
| plugins: | space-separated list of plugins to be used to format the page. They are applied in the specified order, like a chain (or pipeline if you prefer); the output of one is fed to the other. |
| processonly: | if set to yes, the file is processed (i.e. goes through the plugin chain) and the destination directory is created, but the output file is not written to. |
| raw: | can be set to yes in .rdoc nodes and .inc files (sidebar files) to specify that no HTML expansion needs to be performed (i.e. the body is taken as the raw, unprocessed contents of the body section of the file). |
| sidebar: | can be set to a list of filenames separated by spaces, representing entries in the sidebar. Those files are normal rdoc nodes, which must have a title metadata field. Note that $UPPERCASE variable expansion will take place. |
| template: | can be set to a filename (relative to the current directory) containing the template to use. The program will read the file and expand the metavalue to its contents. |
| title: | title of the node. Some plugins might extract the first header and use it as the title. |
Template selection
Node node.rdoc will automatically use the template node.templ if such a file exists in the same directory. This can be overriden with template, as specified above.
Variable Expansion
In some metadata fields and/or body sections, the following variables will be expanded:
| $SRC: | path to the source document (.rdoc file), relative to the directory RDocSite was run from. |
| $SRC_DIR: | path to the source directory (where the .rdoc file is), relative to the directory RDocSite was run from. |
| $ABS_SRC: | absolute path to the source document |
| $ABS_SRC_DIR: | absolute path to the source directory |
| $DEST: | path to the destination document (.html file), relative to the directory RDocSite was run from. |
| $DEST_DIR: | path to the source directory (where the .html file will be), relative to the directory RDocSite was run from. |
| $ABS_DEST: | absolute path to the destination document |
| $ABS_DEST_DIR: | absolute path to the destination directory |
| $ROOT: | path to the site root relative to the current node |
Some fields where variable expansion is performed include (but are not limited to)
- body sections of sidebar entries (.inc files) Common metadata fields
- linklist sections of sitebar entries Common metadata fields
- toplink (TOCFormatter)
- toptext (TopTextFormatter)
- externalcmd (ExternalCommandFormatter)
Sidebar entries
Sidebar entries are specified in the sidebar field, which should look like
sidebar: links.inc lastupdate.inc
In that example, links.inc and lastupdate.inc are files with the same format as rdoc nodes (i.e. metadata and body sections). You should specify the title field since that will be used as the title of that entry.
Tag expansion
Sidebar entries inherit metadata from the enclosing node, with the exception of the title and body fields (since they define their own). Tag expansion is performed in sidebar entries too, so you can have something like the following in a .inc file:
this page was generated using the plugins expand:plugins on expand:date.
NullFormatter
This is a dummy formatter that doesn’t modify the page. It just outputs a message saying that it is processing it; useful for debugging.
TOCFormatter
Can generate a table of contents for the node.
Metadata fields
| gentoc: | if set to yes, the following values will be generated and passed to the template for expansion |
| body: | will be modified to contain links to the TOC in each section, if gentoc is yes. |
| verbosetitle: | generated automatically by taking the first heading unless title is specified |
| toctitle: | title used for the TOC (defaults to Table of contents) |
TopTextFormatter
A TopTextFormatter looks for parent nodes (index, higher in the hierarchy) and extracts the title. It will then interpolate the toptext field with the title and a reference to the parent as in
values["toptext"] % [parent,title]
toptext defaults to
Back to <a href="%s">%s</a>
Moreover, some $UPPERCASE_VARS will be expanded.
If the "inmediate" parent (closer index node) doesn’t exist, the formatter will go higher in the hierarchy until it finds one.
Metadata fields
| toptext: | text that will be interpolated with the link to the parent and its title;
defaults to
Back to <a href="%s">%s</a> |
SiteMapFormatter
If a node is processed with this formatter, a sitemap will be appended at the bottom (the body is not discarded).
ExternalCommandFormatter
It will run a command with system.
Metadata fields
| externalcmd: | command to run. Some $VARS are substituted before running it. | ||||||
| workingdir: | specifies where the command should be run from. Possible values for
workingdir include
|
WebLogFormatter
Nodes processed with this formatter will be aggregated in a blog-like page. The destination node for the blog is set in blognode.
Metadata fields
| blognode: | Space-separated list of destination blog nodes. Defaults to blog/blog. Note that these nodes must exist and should be processed with WebLogMainPageFormatter if you want the blogs to be actually generated. |
| forceblog: | if set to yes, force inclusion into the blogs even if the current node is outside the hierarchy (use with care as this means you cannot always remove a node from the blog area just by moving it). |
One nice property of blognode is that the current file won’t be added to a blog unless it is under the destination blog in the hierarchy (or forceblog is set to yes), so you can specify multiple blog nodes in the "top-level" index.rdoc and sub-blogs will only have their own articles (not those from upper levels).
WebLogMainPageFormatter
Creates a blog in the current node. The body is discarded and replaced with a blog-like static page containing all the nodes associated to the current one (with blognode) that were processed by a WebLogFormatter. The entries are ordered according to their date field.
Metadata fields
| sitebase: | base URL of the blog (to provide a link if RSS is generated). You have to set this to the base URL of your site (for example http://www.mydomain.com). You can set it once in the top-level index.rdoc since your blog nodes will normally share the same value. |
| description: | blog description for the syndication |
| image: | image to be used in the RSS. Example:
http://www.rubygarden.org/ruby.jpg |
| syndication: | a path relative to the site root where the RSS node will be generated (e.g.: blog/syndication). If unset, no RSS will be generated (and the fields above will therefore be ignored) |
| blogsortby: | metadata field that will be used to sort the entries (defaults to date) |
| blogreverse: | if set to yes or unset, the order of the entries will be reversed |
| link: | URL of the blog (generated automatically from the node path and sitebase). |
Entry expansion
Nodes processed with WebLogFormatter will be added to the entries metadata field. Each entry contains at least the following fields:
- title
- title of the entry
- link
- URL of the standalone entry (includes the base URL for the site taken from the blog node’s sitebase). It is generated automatically.
- sitelink
- relative link to the standalone entry from the blog node.
- body
- actual contents of the node
- date
- either specified manually of inferred from the mtime
You might also want to define and use synopsys.
The relevant section of a typical template would look like
START:entries <table class="entry" border="0" cellspacing="0" width="100%"> <tr class="entrytitlebar"> <td rowspan="2" class="entrytitle"><b>%title%</b></td> <td width="20"> </td> IF:date <td class="entrytitledetail">%date%</td> ENDIF:date </tr> <tr class="entrytitlebar"> <td></td> <td class="entrytitledetail">[<a href="%link%">link</a>]</td> </tr> <tr class="entrybody"><td colspan="3" class="entrybody"> IFNOT:synopsis %-body% ENDIF:synopsis IF:synopsis %-synopsis%<br> <a href="%link%">more...</a> ENDIF:synopsis </td></tr> </table> <p /> END:entries
ExpandTagsFormatter
Expands metadata fields into the document; for example
expand:plugins
would be expanded to the list of plugins used in the current node. As in several other cases, you can escape the sequence:
\expand:plugins
will not be expanded (and will result in expand:plugins) even when ExpandTagsFormatter is applied.