Upgrading

Here are step-by-step instructions on how to update your webgen website from 0.4.x to 0.5.x:

  • Update the configuration file config.yaml

    The configuration file syntax as well as the names of the configuration options and some defaults changed. For example, the default processing pipeline now uses kramdown (a Markdown converter) as markup language processor instead of Textile. You can find an overview over all available configuration options in the configuration option reference. Also have a look at the configuration file documentation for more information on the syntax of this file and the available helpers.

    • Name changes: All configuration options now use underscores to separate word parts instead of camelCase.

    • Syntax changes: The configuration options are not specific to a certain extension anymore. You now need the full configuration option name to specify it. So instead of

      Tag/Menu:
  maxLevels: 4

      you now use

      tag.menu.max_levels: 4

  • Convert your metainfo.yaml

    This file is not supported anymore since webgen 0.5.x uses a more flexible way for specifying meta information and virtual paths. You need to migrate its data to metainfo and virtual files in the source directory. Have a look at the documentation of the metainfo source handler and the virtual source handler.

  • Update meta information names and values

    The names of some meta information keys have been changed. Meta information names are not specified in camelCase anymore but with under_scores. You can find a complete list of supported meta information names in the meta information reference. The most notable changes are:

    • directoryName → routed_title
    • inMenu → in_menu
    • indexFile → index_path
    • omitIndexPath → omit_index_path
    • outputNameStyle → output_path_style
    • orderInfo → sort_info

    Also be aware that the syntax of some meta information keys has changed. For example, all meta information keys that took a source path name, e.g. index_path, now take an localized canonical name.

    You need to change the names/value in all places where meta information can be specified:

    • metainfo files
    • virtual files
    • page and template files

  • Files in Webgen Page Format

    Since the format of these files changed a little bit you may need to adapt all your files that use it, that are primarily page and template files. The main change in the format was a different use of the block start line. Whereas before you would write

    --- content, textile

    for specifying the name of the block and its processor, you now can specify any number of options. Two options are currently used by webgen: name and pipeline. So you could change the name and the processing pipeline of a block by using a block start line like:

    --- name:other pipeline:tags,kramdown,blocks

  • Block inclusion in template/page files

    The way how named blocks are included has changed. This feature is now provided by the content processor blocks instead of the tag block. This allows you to specify the point in the processing pipeline when a block should be included. So you definitely need to update your default.template file as well as any other page/template file where you used the block tag.

    So you need to look for {block: content} tags (where content is just a place holder for the name of the block that should be included) and replace them with <webgen:block name='content' />.

  • Update tag names and parameters

    Since the names of the configuration options changed (from using camelCase to using under_scores) and some tags have different options, you need to change all tag parameters. You may also need to convert old tag names to new ones (same reason: camelCase to under_score), for example, includeFile is now include_file.

  • Update your ERB code

    If you have any ERB code in your template or page files you will most certainly have to adapt them to the new API. One thing that has been used often is the check if a page file has a certain block:

    <% if node.node_info[:page_data].blocks.has_key?('NAME') %>
...
<% end %>

    This needs to be changed into the following:

    <% if context.content_node.node_info[:page].blocks.has_key?('NAME') %>
...
<% end %>

  • Extensions development

    Since the complete core of webgen has changed you need to rewrite all your plugins for the 0.5.x series. Howver, webgen has complete API documentation now which provides you with all needed information as well as examples on how to implement source handlers, tags, content processors, … If you still have any questions, don’t hesitate to contact me or write a mail to the mailing list!

  • Running webgen on the converted website

    You now can run webgen 0.5.x on the converted website. This helps in ironing out the remaining errors, for example:

    • If you have forgotten to change a block start line, you will get an application error and the name of the file where the error occured.

    • If you have overlooked changing a tag parameter, you will find ERROR and WARN lines in the log output showing you what still needs to be changed.

  • Not Implement Yet: There are several features of the 0.4.x series which are currently not implemented in the 0.5.x series:

    • source handlers: gallery, sipttra
    • tags: customvar (won’t be ported), download, htmlmetainfo, news (won’t be ported, superceded by blogging support), resource, wikilink
    • misc: smiley replacer, html validators
    • CLI commands: check, show, use

    If you need any of those you have to wait till they are implemented or port them on your on.