webgen supports two new command line options that should make migrating easier:
The first one activates the dry run mode where nothing is actually written to the destination
directory. And the other one displays the would-be-written changes in a
To take advantage of these options you can do the following:
- Create a new empty website directory.
- Add an adjusted webgen configuration file (see the information below).
- Make sure that you modify the sources configuration option to include the path to the old source directory after the new one.
- Also make sure that you point the destination configuration option to your old output directory (this is needed so that the changes can be shown).
- Run webgen and correct one problem after another by copying the problematic files from the old source directory into the new one and fixing them.
Here are step-by-step instructions on how to update your webgen website from 0.5.x to 1.x:
Ruby 1.8 not supported anymore
You need to use Ruby 2.0 or higher if you want to use webgen. Ruby 1.x is not supported!
Update the configuration file
The name of the configuration file changed from
webgen.configso as to clearly signify that this is a webgen configuration file. Furthermore the names of some configuration options as well as the syntax and some defaults have changed.
For example, the default processing pipeline as well as path patterns are not set via configuration options anymore but via meta information paths.
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.
Changed options (names and or syntax):
common.*(not needed anymore because of more flexible tag menu)
passive_sources(passive sources can now be only added programmatically)
sourcehandler.default_meta_info(is now set via a passive meta information path)
sourcehandler.patterns(not needed anymore, can be done via meta information paths and the handler meta information)
tag.menu.*(the tag menu works differently and is much more powerful; the former options have been replaced with new ones)
website.link_to_current_page(generated links now always use the HTML
Update meta information keys and values
The names and partially the syntax of some meta information keys have been changed. You can find the complete list of supported meta information keys in the meta information reference.
The most notable changes are:
blockssyntax changed a bit
cnfor customizing the (a)(l)cn
fragments_in_menuwas removed because it is not needed anymore due to the much more flexible tag menu
kindcan still be used but is not used by any built-in webgen extension anymore
dest_path(and the syntax changed)
routing_pathfor customizing the linked-to path
translation_keyfor customizing the localization strategy
used_nodesis not supported anymore, you need to programmatically add dependencies (see Webgen::ItemTracker#add and the item tracker documentation)
You need to change the key/value in all places where meta information can be specified:
Paths in Webgen Page Format
The format of these files changed a bit but you don’t need to adapt your existing files. A simplified block starting line was added which is very useful when one only wants to name a block.
Update any custom Ruby code
If you have any ERB code in your template or page files or written any extension, you will most certainly have to adapt it to the new API. One thing that has been used often is the check if a page file has a certain block:
<% if context.content_node.node_info[:page].blocks.has_key?('NAME') %> ... <% end %>
This needs to be changed into the following:
<% if node.blocks.has_key?('NAME') %> ... <% end %>
Some other notable changes:
- Webgen::Node::new parameter order changed
- Webgen::Path::new parameters changed, no SourceIO object anymore, access io object directly on path
- Use Webgen::PathHandler#create_secondary_nodes for creating nodes during the generation phase
- Webgen::PathHandler::Base#create_node has a different interface
- Webgen::CLI::Utils::format parameters reordered
Since the complete core of webgen has changed you need to rewrite all your custom extensions. However, webgen has a complete API documentation which provides you with all needed information as well as examples on how to implement path handlers, tags, content processors, …
You may also want to have a look at the
webgen-*repositories on https://github.com/gettalong/ which are the source for some webgen extensions.
If you still have any questions, don’t hesitate to contact me or write a mail to the mailing list!
Built-in extensions that were removed:
- Webgen::Tag::Sitemap is not needed anymore due to the flexible tag menu.
Running webgen on the converted website
Running the new webgen version on the converted website will also help in ironing out the remaining errors.
For example, if you have overlooked changing a tag parameter, you will find
WARNlines in the output showing you what still needs to be changed.