Site structure

To RDocSite, a website is just a hierarchy of nodes plus some data files (images, tarballs, etc). RDocSite reads node information from the source directory, processes this information (the nodes go through a pipeline of formatters), outputs the processed data and copies the data files to the appropriate destination directory.

RDocSite operates on the whole node hierarchy, checking that links between different nodes are correct, etc. Moreover, some formatters can aggregate data from several nodes and create "virtual" nodes.

Nodes

Nodes are created simply by writing a .rdoc file. For your convenience, you can view a node as an entity with two parts:

metadata: values driving the behaviour of RDocSite and the plugins
body: the actual content of the node

Every node has both metadata information and a body, but you can omit the metadata part in your .rdoc file; sensible values will then be used for unspecified metadata fields.

Metadata

The metadata consists of a series of lines such as

  title: Title of the page

  somefield :=   long field
   whose value spans over several lines, and terminated with a
   period on a new line
  .

You can also comment out some parts of the metadata section with the # character:

  # fieldname: this field is commented out

You can view the metadata section as a hash whose keys are the fields, with the values given in the rdoc file. As mentioned before, it is possible to skip the metadata section in a rdoc file; RDocSite will consider that the body has begun when it sees a line that couldn’t possibly belong to the metadata section.

RDocSite uses a powerful mechanism that allows some nodes to export metadata, so that it is inherited by child nodes. This way, a top-level index.rdoc file could specify default values for a number of metadata fields and export them to the other nodes in the site.

Body

The body is simply the text, formatted with RDoc’s markup. This is what you will spend the most time writing. Some plugins can modify the body, too.

Processing the nodes

As said before, to you a node is simply a body of text plus associated metadata. However, to RDocSite, a node is nothing but a hash containing all the associations set in the metadata plus the following

  "body" => "... body ... i.e. text ..."

Formatters

Formatters are given the hash representing a node and return a modified copy where some metadata has been modified, or the body, or some other key => value associations have been added.

The behaviour of the formatters (also named plug-ins) can be controlled using some metadata fields; each plugin recognizes and works on a different set of fields.

Template expansion

In order to create the output pages, a template is used for each node, and it is expanded using the values stored in the hash of the node. For instance, if the template has something like

  The title of this page is %title%.

%title% will be substituted for the value stored in the node-hash. If the hash is {"title" => "Overview", … }, the template will expand to

  The title of this page is Overview.

This means that you can easily create new "expansion variables" that will be expanded in the template, just by defining them in the metadata section.

Consider now what happens to the body section of a node; it is actually stored as an association "body" => real body in the node hash, i.e. exactly like metadata. This means it can be expanded away in the template using the very same mechanism. Therefore, a minimal template could look like

 <html>
        <header><title>%title%</title></header>
        <body>
                %body%
        </body>
 </html>

Copying data files

After generating the output files corresponding to the node hierarchy, RDocSite scans the source directory and recursively copies all data files. It is careful enough to omit the rdoc files and some other associated source files (templates for instance), and ignores .svn subdirectories, for instance.

Table of contents

Site structure
Nodes

Metadata
Body

Processing the nodes

Formatters
Template expansion

Copying data files