webgen 0.5.3 → 0.5.4

data/Rakefile

@@ -162,6 +162,8 @@ EOF
       s.add_development_dependency('rdoc', '>= 2.0.0')
       s.add_development_dependency('coderay', '>= 0.7.4.215')
       s.add_development_dependency('feedtools', '>= 0.2.29')
+      s.add_development_dependency('erubis', '>= 2.6.2')
+      s.add_development_dependency('rdiscount', '>= 1.2.9')
 
       s.require_path = 'lib'
 

data/VERSION

@@ -1 +1 @@
-0.5.3
+0.5.4

data/bin/webgen

@@ -5,5 +5,6 @@ begin
   Webgen::CLI::CommandParser.new.parse
 rescue
   puts 'An error has occurred:   ' + $!.message
+  puts $!.backtrace if $DEBUG
   exit(-1)
 end

data/doc/contentprocessor.template

@@ -2,9 +2,10 @@
 template: extensions.template
 --- name:summary pipeline:erb,tags,maruku,blocks
 
-The short name of the content processor (used, for example, in the `pipeline` option of a block in a
-file in [Webgen Page Format]({relocatable: webgen_page_format.html}) is `<%=
-context.website.config['contentprocessor.map'].invert[context.content_node['title']] %>`.
+As short name for the content processor (used, for example, in the `pipeline` option of a block in a
+file in [Webgen Page Format]({relocatable: webgen_page_format.html})) one of the following can be
+used: `<%= context.website.config['contentprocessor.map'].select {|k,v| v ==
+context.content_node['title']}.map {|k,v| k}.join(', ') %>`.
 
 --- name:content
 <webgen:block name='content' />

data/doc/contentprocessor/blocks.page

@@ -4,8 +4,7 @@ title: Webgen::ContentProcessor::Blocks
 ## Description
 
 This processor replaces a special xml tag with rendered blocks. It is used, for example, in
-templates to define the place where the actual page content should be. The short name of the
-processor is `blocks`!
+templates to define the place where the actual page content should be.
 
 The general syntax is as follows:
 
@@ -27,23 +26,23 @@ This is more easily explained with examples. Assume we have a `default.template`
 
 The `default.template` file:
 
-    --- name:content, pipeline:blocks
+    --- name:content pipeline:blocks
     before default
     <webgen:block name='content' />
     after default 1
-    <webgen:block name='content' chain='page.template;my.page' />
+    <webgen:block name='content' chain='page.template;my.html' />
     after default 2
 
 The `page.template` file:
 
-    --- name:content, pipeline:blocks
+    --- name:content pipeline:blocks
     before page 1
     <webgen:block name='content' />
     after page 1
 
 And the `my.page` file:
 
-    --- name:content
+    --- name:content pipeline:
     The content of the page file.
 
 When `my.page` gets rendered to `my.html`, the node chain looks like this by default:

data/doc/contentprocessor/builder.page

@@ -6,7 +6,7 @@ title: Webgen::ContentProcessor::Builder
 This content processor can be used to programatically create XHTML/XML documents
 ([Reference][1]). The top builder object is provided through the `xml` object. There are also other
 objects provided by webgen available - have a look at the [erb documentation]({relocatable:
-erb.html}). The short name of the processor is `builder`!
+erb.html}).
 
 > This extension is only available if you have installed the [builder][1] library. The preferred way
 > to do this is via Rubygems:

data/doc/contentprocessor/erb.page

@@ -5,7 +5,7 @@ title: Webgen::ContentProcessor::Erb
 
 This processer uses ERB (embedded Ruby) to process content. For detailed information about ERB have
 a look at its documentation by executing `ri ERB` or the [ruby documentation
-site](http://www.ruby-doc.org/)! The short name of the processor is `erb`!
+site](http://www.ruby-doc.org/)!
 
 You can use the following special objects in your ERB code:
 

data/doc/contentprocessor/erubis.page

@@ -0,0 +1,46 @@
+---
+title: Webgen::ContentProcessor::Erubis
+---
+## Description
+
+This processor uses the [Erubis][1] library to process embedded Ruby statements. Erubis is quite a
+bit faster than the standard ERB library that is shipped with Ruby and provides many other useful
+options.
+
+> This extension is only available if you have installed the [erubis][1] library. The preferred
+> way to do this is via Rubygems:
+>
+>     gem install erubis
+{.exclamation}
+
+[1]: http://www.kuwata-lab.com/erubis/ "Erubis Homepage"
+
+You can use some special objects provided by webgen in your embedded Ruby code. These are the same
+objects that are available to the `erb` processor, have a look at its [documentation
+page]({relocatable: erb.html}).
+
+The default mode of Erubis works like ERB. So everyting said on the [erb page]({relocatable:
+erb.html}) is also true for Erubis. However, you can customize how this processor works by using the
+following configuration options:
+
+* `contentprocessor.erubis.use_pi`: Use processing instructions instead of ERB like
+  instructions. Normally you use statements like `<%% result = some_method_call(opts) %>` or `<%%=
+  context.content_node.absolute_lcn %>` in your content. When setting this option to `true`, you can
+  use XML processing instructions instead, like this: `<?rb result = some_method_call(opts) ?>` or
+  `@{context.content_node.absolute_lcn}@`.
+
+* `contentprocessor.erubis.options`: This is hash which is passed to the Erubis interpreter and
+  which can be used to set additional options.
+
+For more information on the additional options or on how to use the processing instructions mode of
+Erubis, have a look at the [Erubis User Guide](http://www.kuwata-lab.com/erubis/users-guide.html)!
+
+You can also use block options to modify the behavior of Erubis. The block option `erubis_use_pi` is
+used instead of the configuration option `contentprocessor.erubis.use_pi` and all other block
+options starting with `erubis_` are added the options hash that is passed to the Erubis
+interpreter. For example, the following page tells the Erubis interpreter to use the processing
+instructions mode and to trim spaces:
+
+    --- erubis_use_pi:true erubis_trim:true
+    Here are the numbers from 1 to 5:
+    <?rb for i in [1,2,3,4,5] ?>@{i}@<?rb end ?>

data/doc/contentprocessor/haml.page

@@ -5,7 +5,7 @@ title: Webgen::ContentProcessor::Haml
 
 This processor converts the content, which is assumed to be in the Haml markup language, to valid
 XHTML by using the Haml library. For detailed information about Haml have a look at the [Haml
-Homepage][1]! The short name of the processor is `haml`!
+Homepage][1]!
 
 You can use some special objects provided by webgen in your Haml markup. These are the same objects
 that are available to the `erb` processor, have a look at its [documentation page]({relocatable:

data/doc/contentprocessor/maruku.page

@@ -6,7 +6,7 @@ title: Webgen::ContentProcessor::Maruku
 This processor converts the content, which is assumed to be in Markdown markup, to HTML by using the
 Maruku library. Maruku is a Markdown processor which supports a superset of Markdown, including
 support for assigning ids and classes to every element, support for Markdown inside HTML elements
-and footnotes. The short name of the processor is `maruku`!
+and footnotes.
 
 For detailed information about Maruku have a look at the [Maruku Homepage][1]. There you will find
 information about the general Markdown syntax as well as information about the extras added by

data/doc/contentprocessor/rdiscount.page

@@ -0,0 +1,37 @@
+---
+title: Webgen::ContentProcessor::RDiscount
+---
+## Description
+
+This processor converts the content, which is assumed to be in Markdown markup, to HTML by using the
+RDiscount library. This library is based on the C based discount library which provides very fast
+Markdown processing. However, this processor does not support advanced features like the [Maruku
+Markdown processor]({relocatable: maruku.html}) does.
+
+> This extension is only available if you have installed the [rdiscount][1] library. The preferred
+> way to do this is via Rubygems:
+>
+>     gem install rdiscount
+{.exclamation}
+
+[1]: http://github.com/rtomayko/rdiscount
+
+Example
+-------
+
+Here is a short sample of a text in Markdown markup:
+
+    # This a h1 header
+
+    You can just write *your* paragraphs here and
+    [link][1] them below. This is **nice** format!
+
+    > Citations are easy too.
+    > Really. And you can assign them attributes.
+
+    * Lists
+    * aren't
+    * difficult
+    * either.
+
+    [1]: http://someurl.com

data/doc/contentprocessor/rdoc.page

@@ -4,7 +4,7 @@ title: Webgen::ContentProcessor::RDoc
 ## Description
 
 This content processors converts content written in RDoc markup (the default documentation format
-for Ruby source files, [reference][1]) to HTML. The short name of the processor is `rdoc`!
+for Ruby source files, [reference][1]) to HTML.
 
 > This extension needs the [new RDoc implementation][2] and is not compatible with the
 > implementation included in the Ruby distribution. The preferred way to install the new

data/doc/contentprocessor/redcloth.page

@@ -5,7 +5,6 @@ title: Webgen::ContentProcessor::RedCloth
 
 This processor converts the content, which is assumed to be in Textile markup, to HTML by using the
 RedCloth library. For detailed information about Textile have a look at the [Textile Reference][1]!
-The short name of the processor is `redcloth`!
 
 > This extension is only available if you have installed the [redcloth][2] library. The preferred
 > way to do this is via Rubygems:

data/doc/contentprocessor/sass.page

@@ -5,7 +5,6 @@ title: Webgen::ContentProcessor::Sass
 
 This processor converts the content, which is assumed to be in the Sass meta language, to valid CSS
 using the Haml library. For detailed information about Sass have a look at the [Haml Homepage][1]!
-The short name of the processor is `sass`!
 
 > This extension is only available if you have installed the [haml][1] library. The preferred way to
 > do this is via Rubygems:

data/doc/contentprocessor/tags.page

@@ -7,7 +7,7 @@ This processor provides an easy method for adding dynamic content to web pages.
 webgen tags to replace special markup constructs with dynamic content. This system allows webgen to
 generate menus and breadcrumb trails, include files and much more. webgen already comes with many
 tags that handle simple things, like including a file, to advanced things, like generating a
-menu. The short name of the processor is `tags`!
+menu.
 
 Each webgen tag is defined using a unique name and handled by a tag class. A tag can have zero or
 more parameters some of which are mandatory. Tag parameters map directly to configuration options,

data/doc/extensions.page

@@ -1,14 +1,9 @@
 ---
 title: Extensions
 ---
-# webgen Extensions
+# Extension Listing
 
-webgen comes with many extensions that allow for rapid creation of static websites. The variety of
-the extensions allows you to use your tools of choice, for example, your preferred markup
-language. And if your choice is not available, you can write the extension for it yourself or make a
-feature request!
-
-Here is a list of all extensions:
+Following is a listing of all available extensions:
 
 <%
 pattern = /#{File.join(node.parent.absolute_lcn, '/')}(contentprocessor|output|source|sourcehandler|tag|)\//

data/doc/faq.page

@@ -3,9 +3,36 @@ title: FAQ
 ---
 # General Questions
 
-> This section does not have any content yet. If you have any good questions, please write an email!
-{.exclamation}
+*   **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 ...
 
@@ -53,13 +80,11 @@ The value needs to be a valid ISO-639-1/2 language code.
 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_meta_info:
-      Webgen::SourceHandler::Page:
-        blocks:
-          default:
-            pipeline: erb,tags,textile,blocks
+    default_processing_pipeline:
+      Page: erb,tags,textile,blocks
 
-Substitute the value of the `pipeline` key approriately.
+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:
 
@@ -72,7 +97,7 @@ Use the configuration file! For example, to change the meta information `in-menu
 to `true` for all page files use the following in your configuration file:
 
     default_meta_info:
-      Webgen::SourceHandler::Page:
+      Page:
         inMenu: true
 
 The key `default_meta_info` is a special key in the configuration file which allows to update the
@@ -102,7 +127,7 @@ You have several options of varying granularity:
   output paths of this source handler (the page source handler in the following example):
 
       default_meta_info:
-        Webgen::SourceHandler::Page:
+        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
@@ -151,9 +176,9 @@ There are many ways to accomplish this, I will show only one way here using bloc
 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') %>
+    <%% if node.node_info[:page].blocks.has_key?('sidebar') %>
       \<webgen:block name='sidebar' />
-    <% end %>
+    <%% 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
@@ -175,3 +200,15 @@ Webgen::ContentProcessor::Builder!
 
 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}

data/doc/index.page

@@ -3,14 +3,14 @@ title: Overview
 in_menu: false
 ---
 
-This documentation is for the *repository version* of webgen and therefore may state features that
-are not available in the latest released version.
+This documentation is for the *repository version*{: style='color: red; font-weight: bold'} of
+webgen and therefore may state features that are not available in the latest released version.
 
-* The documentation for the latest released 0.5.x version can be found
-  [here](http://webgen.rubyforge.org/documentation/0.5.x/index.html)
+* The documentation for the *latest released 0.5.x*{: style='color: red; font-weight: bold'} version
+  can be found [here](http://webgen.rubyforge.org/documentation/0.5.x/index.html)
 
-* If you are looking for the documentation of the 0.4.x series, it can be found
-  [here](http://webgen.rubyforge.org/documentation/0.4.x/index.html).
+* If you are looking for the documentation of the *0.4.x*{: style='color: red; font-weight: bold'}
+  series, it can be found [here](http://webgen.rubyforge.org/documentation/0.4.x/index.html).
 
 If you don't find an answer to your questions in the documentation, there are also:
 
@@ -36,9 +36,9 @@ a reference, go to one of the following pages:
   here. After reading the Getting Started Guide, this should be the next read. Have a look at the
   section headers to get a quick overview of what can be found here.
 
-* [**FAQ**]({relocatable: faq.html}): If you want to do something with webgen, but you don't know how,
-  this page is exactly for you. It provides answers to frequently asked questions. If you have a
-  question which you think should be added, just mail me.
+* [**FAQ**]({relocatable: faq.html}): If you want to do something with webgen, but you don't know
+  how, this page is exactly for you. It provides answers to frequently asked questions and
+  HowTos. If you have a question which you think should be added, just mail me.
 
 * [**Upgrade information**]({relocatable: upgrading.html}): This document provides some information
   on upgrading a website from the 0.4.x to the 0.5.x series.

data/doc/manual.page

@@ -1,6 +1,16 @@
 ---
 title: Manual
 ---
+# Introduction
+
+This manual describes all of webgen in as much detail as possible. If you still find something
+missing, don't hesistate to write a mail to the mailing list!
+
+The manual is structured in such a way that it can be read from top to bottom while creating a
+webgen website. This means that first the information on how to use the webgen CLI comes, then how a
+webgen website is structured and how content can be added and so on.
+
+
 
 # The `webgen` command
 
@@ -55,21 +65,23 @@ Following is a short overview of the available commands:
 # A webgen Website {#website}
 
 webgen needs a special directory structure so that it works out of the box. This directory structure
-is automatically created by the `webgen create` command.
+is automatically created by the `webgen create` command. You can alternatively use the webgui to
+create the website directory.
 
 The root directory of webgen website is called the website directory. You can have the following
 files and directories under this directory:
 
 * `src`: The source directory in which all the source files for the website are. If this directory
-  is not called `src` or you want to include additional source directories, you need to change the
-  `sources` configuration option.
+  should not be called `src` or you want to include additional source directories, you need to
+  change the `sources` configuration option.
 
 * `out`: This directory is created, if it does not exist, when webgen generates the HTML files. All
-  the output files are put into this directory. This directory can be changed by setting the
-  `output` configuration option.
+  the output files are put into this directory. The name of this directory can be changed by setting
+  the `output` configuration option.
 
 * `ext`: The extension directory (optional). You can put self-written extensions into this directory
-  so that they are used by webgen.
+  so that they are used by webgen. See the [extension directory]({relocatable: '#website-ext'})
+  section for more information.
 
 * `config.yaml`: This file can be used to set configuration options for the website. See the
   [Configuration File]({relocatable: '#website-configfile'}) section for more information.
@@ -78,6 +90,14 @@ files and directories under this directory:
   some useful tasks out of the box. See the [Rakefile]({relocatable: '#website-rakefile'}) section
   for more information.
 
+## Extension Directory {#website-ext}
+
+The extension directory is used for modifying core behaviour of webgen or adding extensions. It is
+called `ext` and has to reside directly under the website directory. All files called `init.rb` in
+this directory or any of its subdirectories are loaded when webgen renders the website. So you need
+to make sure to either place all extensions in `init.rb` or load them from this file. The latter
+approach is better since you can use the lazy loading feature that webgen uses internally,
+ie. extensions are loaded only when they are needed.
 
 ## Configuration File {#website-configfile}
 
@@ -123,6 +143,29 @@ keys to help setting these configuration options:
           Page:
             in_menu: true
 
+*   `default_processing_pipeline`: Set the default processing pipeline for one or more source
+    handlers.
+
+    This key needs a Hash as value which should be of the following form:
+
+        SOURCE_HANDLER_NAME: PIPELINE
+
+    Each key-value pair specifies the name of a source handler and the new default processing
+    pipeline. The value for the processing pipeline has to consist of the short names of content
+    processors separated by commas and normally includes `erb`, `tags`, `blocks` and the name of a
+    content processor for a markup language. The short name(s) of a content processor is (are)
+    stated on its documentation page. Be aware that the content processors are executed in the order
+    in which they are specified!
+
+    If a source handler called `Webgen::SourceHandler::SOURCE_HANDLER_NAME` exists, the meta
+    information is set for this source handler instead.
+
+    For example, the following snippet of a configuration file sets the default processing pipeline
+    for 'Webgen::SourceHandler::Page':
+
+        default_processing_pipeline:
+          Page: erb,tags,textile,blocks
+
 *   `patterns`: Set the used path patterns for one or more source handlers.
 
     This key needs a Hash value and provides two different ways of setting the path patterns:
@@ -146,8 +189,6 @@ keys to help setting these configuration options:
           Copy:
             add: [**/*.pdf]
 
-
-
 ## Rakefile {#website-rakefile}
 
 The Rakefile that is automatically created upon website creation provides a place to specify
@@ -183,8 +224,8 @@ You can naturally use any other type of file. However, be aware that some files
 by webgen when no source handler class for them exists. For example, there is currently no source
 handler class for `.svg` files, so those files would be ignored. If you just want to have files
 copied from a source to the output directory (like images or CSS files), the SourceHandler::Copy
-class is what you need! Look through the documentation of the availabe source handler classes to get
-a feeling of what files are handled by webgen.
+class is what you need! Look through the documentation of the [availabe source handler
+classes]({relocatable: extensions.html}) to get a feeling of what files are handled by webgen.
 
 
 ## Source Paths Naming Convention {#source-naming}
@@ -270,6 +311,10 @@ the (localized) canonical name! This is different from previous webgen versions!
 
 ## Output Path Name Construction ### {#source-output}
 
+There is currently only one method, called `standard`, for creating output path names which is
+described here. However, webgen allows developers to create other output path name creation
+methods. More information on this can be found in the [API documentation]({relocatable: api.html}).
+
 The output path for a given source path is constructed using the meta information
 `output_path_style`. This meta information is set to a default value and can be overwritten by
 setting it for a specific source handler or for a path individually. The value for this meta
@@ -278,10 +323,12 @@ information key is an array which can have the following values:
 * strings (for inserting arbitrary text into output names)
 * arrays (for grouping values - only interesting for the language part)
 * symbols for inserting special values:
-  * `:cnbase`: the basename of the path
-  * `:parent`: the parent path
-  * `:lang`: the language
-  * `:ext`: the file extension including the leading dot
+  * `:cnbase`: The basename of the path.
+  * `:parent`: The parent path.
+  * `:lang`: The language.
+  * `:ext`: The file extension including the leading dot.
+  * `:year`, `:month`, `:day`: The creation year, month and day, respectively, of the source path.
+    An error is raised if the needed meta information `created_at` is not set on the path.
 
 > The contructed output path must always be an absolute one, ie. it has to start at the root of the
 > output directory. Therefore, the `:parent` part should always be included!
@@ -315,7 +362,13 @@ the default language and that the path is under a directory called `/img/`):
 
     *   `index.jpg` --> `/img/index.jpg.`
 
-        Be aware of the trailing dot since the `:lang` value is not defined in an sub array!
+        Be aware of the trailing dot since the `:lang` value is not defined in a sub array!
+
+*   `output_path_style=[:parent, :year, /, :month, /, :cnbase, [., :lang], :ext]`
+
+    *   `index.jpg` --> `/img/2008/09/index.jpg`
+
+        This output path style can be used to create blog archive style output names.
 
 
 ## Path Patterns {#source-pathpattern}
@@ -429,16 +482,51 @@ There is clearly defined order in which meta information is applied to a node fo
 
 
 
+# webgen Extensions
+
+webgen comes with many extensions that allow for rapid creation of static websites. The variety of
+the extensions allows you to use your tools of choice, for example, your preferred markup
+language. And if your choice is not available, you can write the extension for it yourself or make a
+feature request!
+
+Extensions are only loaded when they are needed. For example, if you don't use `.feed` files for
+automatically generating atom/RSS feeds for your website, the source handler that handles these
+files will never be loaded. Therefore you don't need to explicitly enable extensions, they just sit
+in the background and wait till the webgen core needs them.
+
+There are several types of extensions:
+
+*   **Content Processors**: These extensions process content, for example, the content of files in
+    Webgen Page Format. It is not specified how they have to process the content but this type of
+    extension can basically be divided into two groups:
+
+    * Markup processors: Processors like Maruku or RedCloth belong to this group and they convert
+      markup text that is easy to read and write to a more structure format like HTML. This allows
+      you to write an HTML page without knowing HTML.
+
+    * String replacers: These processors normally process special strings and substitute them with
+      other content. For example, the `erb` processors replaces delimited strings interpreted as
+      Ruby code with the interpreted value. Another example would be webgen's `tags` processor which
+      replaces strings like `\{relocatable: ../index.html}` with a processed value.
+
+*   **Source Handler**: These extensions are used for handling source paths. They read the content of
+    a path and produce one or more nodes (the internal representation of an output path, see [source
+    handling]({relocatable: '#source-handling'}) for more information on nodes). So a source handler
+    can do something simple like just copying a source path to the output directory but they can
+    also do complex things like creating a whole image gallery from just one source path.
+
+*   **Tags**: This type of extension allows the easy inclusion of dynamic content in, for example,
+    page and template files. Each tag extension is used for a specific task like creating a menu or
+    a breadcrumb trail.
+
+
+
 # Extending webgen
 
 If you know the programming language Ruby a little bit, you can easily extend webgen and add new
 features that you need. All the needed developer documentation is available in the [API
 documentation](rdoc/index.html), along with sample implementations for all major types of extensions
 (source class, output classes, source handler class, content processors classes, tag classes, ...)
-and detailed information about the inner workings of webgen.
-
-webgen allows one to add extensions to a website by placing them in the directory `ext` under the
-website directory. All files called `init.rb` in any directory are loaded when the Webgen::Website
-gets initialized. So you need to make sure to either place all extensions in `init.rb` or load them
-from this file.
-
+and detailed information about the inner workings of webgen. Have a look at the [extension
+directory]({relocatable: '#website-ext'}) section for more information on naming files and where to
+put the extensions.