Webgen Page Format

The Webgen Page Format is a custom format designed primarily for page and template files. It consists of an optional meta information block and one or more blocks of data; it is very simple and easy to use.

Structure

A file using the Webgen Page Format consists of one or more blocks which are the smallest units recognized. Blocks are separated from each other through a line containing three dashes. This is illustrated in the following examples which are all valid files in WebPage Format:

Example 1:

Here is a block!

Example 2:

This is one block of the file
---
This is another block.

Example 3:

Block 1
--- name:block2
Block 2
--- name:block3
Block 3...

If you want to use three dashes in a block but you don’t want to end the block, you have to escape them with a backslash character, like this:

Block 1
\---
still Block 1
--- name:block2
Block 2

All of the above examples show one kind of block, the content block. However, there may also be another type of block: the meta information block. Following is a short description of both kinds, starting with the meta information block.

Meta Information Block

Each file in Webgen Page Format can have zero or one meta information blocks. This block is specified at the beginning of the file. To tell the parser that the first block is the meta information block and not a content block, you have to start the file with three dashes:

---
title: The title set by Meta info
---
This is the content of the file

The above defines a meta information block and a content block. The meta information block has to be in YAML format and should contain key-value pairs of meta information. YAML is a simple markup language designed for ease of use and although you define structured data with it, it feels like just writing a plain text document.

Content Blocks

A content block is used to provide content in a specific format. Each file in Webgen Page Format needs to have at least one content block which may be empty. However, it can have as many content blocks as necessary. This functionality can be used, for example, to provide the main content of an HTML page in one block and sidebar content in another one.

Each content block needs to have a unique name and additional options can also be set. The name uniquely identifies a content block and is used to access it. The only option used by webgen is the pipeline option which specifies the processing pipeline for the block. The processing pipeline is used for rendering the block by using the specified content processors in the specified order. There are many different content processors available - have a look at the extensions page for an overview.

webgen extensions that use files in Webgen Page Format may specify defaults for the name and the options of a block but these defaults can be overwritten. You can use one of two ways to do this:

  • you either specify the name and additional options of the block on the starting line with the three dashes

  • or you use the special meta information block to define the names and options of one or all blocks.

The following example uses the first technique to override the name and/or the pipeline option:

1. content block of the file
--- name:sidebar pipeline:kramdown,tags
2. content block of the file
--- name:other
3. content block of the file

The first block has no identifieres set (there is no line with three dashes and the identifieres). Therefore the default value for the name is used: content. The second block is named sidebar and uses the processing pipeline kramdown,tags. As you can see, the name of a block as well as additional options are specified by stating the key (e.g. name or pipeline) followed by a colon and the value. Multiple options are separated via one or more spaces. The value of a block option is parsed with YAML. For example, when specifying use_something:true the value true is automatically converted from the string true to the boolean true.

Only the first block gets the default name of content. The second and following blocks have numbered names like block2, block3 and so on.

You can also set the name and additional options of the content blocks by using the special blocks meta information. It is a hash using the index of a block (or the special value default) as key and the options as values. The above example can therefore also be written like this:

---
blocks: {2: {name: sidebar, pipeline: kramdown,tags}, 3: {name: other}}
---
1. content block of the file
---
2. content block of the file
---
3. content block of the file

When selecting a value for the name of a block or an option, the following precedence is used (from low to high):

  • global defaults set via the default key of the meta information blocks
  • block defaults set via the meta information blocks
  • the --- line options

As stated above, the “option” name is special insofar that when it is not set, an automatic name gets generated.