---
title: FAQ
---
# General Questions

*   **webgen fails with an error after upgrading to a newer version - what to do?**

    Delete the cache file and try again. The structure of the cache may not be valid anymore after a
    version update. So it is always good to delete the cache after installing a new webgen version.

*   **Why can I specify multiple blocks in a page/template file?**

    This allows you to provide different content parts for one page. For example, image you have a
    layout with a sidebar and you want to have page specific sidebar contents. The easiest way to
    achieve that is to add a `sidebar` block to the page files that provide a page specific sidebar
    content and conditionally include the `sidebar` block in your `default.template`, like this:

        <%% if node.node_info[:page].blocks.has_key?('sidebar') %>
          \<webgen:block name='sidebar' />
        <%% end %>

*   **What do I have to do to use the extensions?**

    Nothing! Extensions are initialized and used automatically when needed. So, for example, if you
    add a `my.feed` file to your website, the `Webgen::SourceHandler::Feed` extension gets
    automatically used. The same is true for all types of extensions (source handler, content
    processors, tags, ...).

*   **Is there any way to add comments to my webgen website?**

    Surely! There are several comment engines out there, however, the following two look very
    promising:

    * [JS-Kit](http://js-kit.com/comments/)
    * [DISQUS](http://disqus.com)

# How to ...

This section provides quick answers and links to more information for the most commonly asked
questions.

### ... create a website?

Use the `webgen` command to create the needed directories

    webgen create -t project -s andreas07 my_site

This will create a webgen website in the directory `my_site` using the specified template and style.

### ... set configuration options?

You can set any configuration options via the configuration file called `config.yaml`. For example,
say you want to set the option `website.link_to_current_page` to `true`, then you would add the
following to the configuration file:

    website.link_to_current_page: true

There is a second possibility for webgen tags: you can set the options directly in the tag
definition, like this:

    \{menu: {start_level: 2, min_levels: 3}}

And if you want to have complete control over the configuration options, you can use the file
`ext/init.rb`. For example, the following specifies that all page files should be in the menu by
default:

    config = Webgen::WebsiteAccess.website.config
    config['sourcehandler.default_meta_info']['Webgen::SourceHandler::Page']['in_menu'] = true

### ... change the default language?

To use, for example, German as the default language, put the following into the configuration file:

    website.lang: de

The value needs to be a valid ISO-639-1/2 language code.

### ... use a different processing pipeline for page files?

If you want to change the processing pipeline (ie. how a page file get rendered), you need to add
the following to your configuration file:

    default_processing_pipeline:
      Page: erb,tags,textile,blocks

The `default_processing_pipeline` key is a special key which allows to directly set the processing
pipeline (instead of going through all the meta information).

If you just want to change the pipeline for one block, you can do it like this:

    --- pipeline:erb,tags,textile,blocks
    This is the content of the block

### ... set the default meta information for files created by a specific source handler?

Use the configuration file! For example, to change the meta information `in-menu` sothat it defaults
to `true` for all page files use the following in your configuration file:

    default_meta_info:
      Page:
        inMenu: true

The key `default_meta_info` is a special key in the configuration file which allows to update the
default meta information for a source handler and not to substitute it.

### ... ignore files in the source directory?

This can be done using the `sourcehandler.ignore` configuration options. For example, to ignore all
files starting with `core`, you would put the following in the configuration file:

    sourcehandler.ignore: [**/core*]

The value of this option has to be an array of path patterns. Be aware that this overwrites the
default setting.

### ... change the output name style?

You have several options of varying granularity:

* Set the meta information `output_path_style` for all source handlers:

      default_meta_info:
        :all:
          output_path_style: [:parent, :cnbase, [., :lang], :ext]

* Set the meta information `output_path_style` for a specific source handler to only change the
  output paths of this source handler (the page source handler in the following example):

      default_meta_info:
        Page:
          output_path_style: [:parent, :cnbase, [., :lang], :ext]

* Add the meta information `output_path_style` to a single file via, for example, a meta information
  backing file.

### ... modify the template chain?

To stop the template chain at a specific template or even at the page file itself, specify a
null template in the meta information, like this:

    template: ~

To nest templates, you just need to specify the template, in which this template/page file should be
nested, in the meta information:

    template: my_special.template

Be aware that if no `template` meta information is specified for a page or template file, the
template handler automatically searches for a default template in the directory and the parent
directories of the file!

### ... localize a directory name?

Just set the `routed_title` meta information on the correct localized directory index files.

### ... provide additional attributes on links to a file?

You can specify additional attributes for a link to a file by using the `link_attrs` meta
information. Take the following page file:

    ---
    title: Tutorial
    in_menu: true
    link_attrs:
      title: This is a rather large tutorial
      accesskey: D
      tabindex: 5
    ---
    Yippieh, this is my tutorial!

When a link to this page is created, the specified attributes get additionally set on the link!

### ... add page specific sidebar content?

There are many ways to accomplish this, I will show only one way here using blocks. Add the
following to the sidebar part in your `default.template` (ensure that you haven't disabled `erb` in
the processing pipeline):

    <%% if node.node_info[:page].blocks.has_key?('sidebar') %>
      \<webgen:block name='sidebar' />
    <%% end %>

This will include the contents of the block `sidebar` in the sidebar if such a block exists for a
page. You can then add a sidebar block to each page file which needs it. Following is such a sample
page file:

    This is the main content block
    --- sidebar
    This is the sidebar block and everything in here goes to the sidebar!

### ... create XML output?

This can be achieved manually (by removing any markup processor in the processing pipeline of the
page file and then directly creating the XML elements) or by changing the processing pipeline to
include content processor `builder` which provides an easy way of programmatically creating an XML
compliant file. More information on this can be found on the documentation page of
Webgen::ContentProcessor::Builder!

### ... create a static menu?

You can use virtual nodes to define virtually any menu structure you like, including things like
having menu entries that point to the same page and links to external pages.

### ... use short menu title?

You can use a special of the meta information `link_attrs` to achieve that. Just use the following
in the meta information block of the page file for which you want a short menu title:

    link_attrs:
      :link_text: Short title

> Be aware that this changes not only how the page appears in a menu but also how it appears in
> breadcrumb trails and other links generated by webgen.
{.exclamation}