User Guide


Before you install Yggdrasil, you must have a working installation of Perl version 5.8.0. You can download Perl from one of the following locations: - source code distribution and links to binary distributions for various platforms - Windows, Linux and Solaris binaries

Install Yggdrasil

Unzip and extract the distribution to the desired directory. All files are in a directory named yggdrasil. After extracting the files, you can run Yggdrasil with

   perl [OPTIONS]


   ./ [OPTIONS]

depending on your OS and system setup. Run

   perl --help

to display a description of the available commandline options.

Install required modules

Yggdrasil uses a couple of modules which are not included in the standard Perl distribution. Use the CPAN shell (Linux) or PPM (Windows) to install the modules on your system:

Using CPAN:

    perl -MCPAN -eshell
    install AppConfig
    install Date::Format
    install Text::Template

Using PPM:

    ppm install AppConfig
    ppm install TimeDate
    ppm install Text-Template

AppConfig is not available from the default ActiveState repository. Use instead.

Install SP

If you want to validate your HTML documents as they are being built, you need to install the SP SGML System:

SP comes with Document Type Definitions (DTD) for HTML versions up to 4.0. If you want to validate XHTML documents you need to download the correct DTD’s from the World Wide Web Consortium: - XHTML 1.0 - XHTML 1.1

Unzip the file you downloaded and copy the DTD’s to SP’s pubtext/ directory.


See the Quick Start Guide.



Yggdrasil handles most of the intersite navigation automatically. Use the following features to take advantage of this.

Links to subpages

Links to all subpages of the current page are placed in the @navigation template variable. The array contains reference to hashes with the following keys: name and href. Name is the title of the page and href is the relative path from the current page to the subpage.

The array is sorted alphabetically on the value of the name key, but you can use a snippet of code in your template to sort it any way you like.

Whether a page shows up in the @navigation variable depends on your settings for the include and exclude configuration variables.

Breadcrumb trail

Links to all index pages in the path from the current page to the root page are placed in the @trail template variable. The array contains references to hashes with the same keys as those in the @navigation template variable.

In the default configuration, all links in the breadcrumb trail are relative with no file names (e.g. ../../). This means that for the trail to work you must have HTML index files (as determined by the html_indices configuration variable) in all directories of the site.


Links to all files in the current directory are placed in the @siblings template variable. The array contains references to hashes with the same keys as those in @navigation template variable. For non-HTML files the filename is used in the name field.

Numbered subpages

Content spanning multiple pages is handled by the numbered subpages feature. This feature requires that you use a specific directory layout for your content. E.g. for content spanning three pages you must use the following directory structure:

        index.html       First page
            index.thml   Second page
            index.html   Third page

On pages 2 and 3 the page number is appended to the breadcrumb trail (in the form ‘Page n’). Yggdrasil doesn’t create links to the numbered subpages, you have to create your own ‘next/previous page’ links.


Template overrides

Use this feature when you have set up your source with a base template for one target but you need to override this for a different target without having to maintain duplicate source directories. This can also be useful when you need to publish a subdirectory of your main source directory to a different target.

FIXME: description of template override syntax


Misc. features.


Yggdrasil can upload all processed files via FTP. You need to set a hostname, a username nad a password for this feature to work (an optional remote path can also be set).

Yggdrasil can delete remote files that are no longer in use, but it has no support for deleting empty directories.

FIXME: config file syntax


If you have installed the SP SGML System, you can have Yggdrasil validate your output files as they are being generated. Any errors found will be reported when all files have been processed.

You must define the full commandline needed to start nsgmls in the sp_command_line configuration variable (an example is included in conf/default.cfg. The variable $filename will be replaced with the name of the file being processed.

Enable validation with the --validate commandline option or by setting validate=1 in the configuration file.

Offline sites

The default navigation generated by Yggdrasil is only suitable for use on a properly configured webserver. To prepare your site for offline use you need to inlcude filenames in all navigation links.

Set include_index=1 in the configuration file to include filenames in all links.


When preparing alternate versions of your site you might need to perform some kind of postprocessing on the output files.

To use the postprocessing feature, you must create a file containing an anonymous subroutine. This file must be named according to your configuration file. If you are using default.cfg, the file containing the subroutine must be named default.sub and be placed in the conf/ directory.

FIXME: text about input/output of postprocessing sub.

Log file

If you need to process the files with other tools, you can use a log file to get a list of all the processed files.

FIXME: text about headers, footers and line templates.


Configuration variables

The examples below use the configuration file syntax.

Path to source directory.
    input_dir = /home/me/site/source
Path to output directory.
    output_dir = /home/me/www
Directory used to store title and update time caches.
    data_dir = data
Directory create mode used by mkpath().
    dir_mode = 0755
Files matching one or more of the regular expressions in this array are passed to Text::Template. Files that do not match any of the regular expressions are copied to the target directory without processing. Should only match HTML files.
    include = \.html$
    include = \.shtml$
Files or directories matching one or more of the regular expressions in this array are not processed or copied. These regular expressions are applied before the regular expressions in the include array.
    exclude = ^_
    exclude = \.tmpl$
    exclude = ~$
Directories matching one or more of the regular expressions in this array are not included in the @navigation array.
    skip = ^img
    skip = ^index$
Passed to templates.
    base_url =
Filename of base template. All parent directories of the current directory are searched.
    base_template = base.tmpl
File extension of template files. Used when seraching the current path for templates.
    template_extension = .tmpl
A hashref containing full paths to override templates. If used, there must be at least a ‘default’ override. Other overrides are matched against the current file name. E.g. an override template named ‘beta’ will be applied to all files matching /beta/.
    template_override beta = /home/me/site/template.tmpl
Format of the timestamp passed to the template. FIXME: add link to Date::Format manpage.
    timestamp_format = %a %b %e %Y (%T)
These filenames are removed from URL’s in the breadcrumb trail. Should match your webserver configuration.
    html_indices = index.html
    html_indices = index.shtml
Set to 1 to give all HTML files (the files in include) the extension .html (this is useful when creating site versions for offline use or for webservers that can’t handle SSI).
    html_only = 0
Set to 1 to create a navigation array for the top level of the site (useful when creating site versions for offline use).

FIXME: note on how this is usually not necessary because of global site navigation already in place.

    front_page_navigation = 0
Set to 1 to include ‘index.html’ in navigation and breadcrumb trail links (useful when creating site versions for offline use).
    include_index = 0
Set to 1 to include index files in the siblings array.
    siblings_include_index = 0
Name given to the root page in the breadcrumb trail.
    home_label = Home
The tag in the source HTML document used as the document title.
    title_tag = h1
Title given to files not found in the title cache.
    default_title = No Title
Set to 1 to enable the numbered subpages feature (see User Guide).
    subpages = 1
Page title added to the breadcrumb trail for numbered subpages.
    pagination = Page
URL or IP address of FTP server.
    ftp_host =
FTP server username.
    ftp_username = me
FTP server password.
    ftp_password = secret
Base path to use for remote files.
    ftp_path = /www
The first line(s) of the log file.
    log_file_header = # Yggdrasil log file
The last line(s) of the log file.
    log_file_footer = # end of log file
Template for log file lines. The following variables are available: $fullname, $dirname, $filename.
    log_file_format = {$fullname}
Name of the file containing the last site release time. Stored in current data directory.
    release_file = .release
Set this to the complete commandline for nsgmls if you wish to validate output files while processing. {$filename} is replaced with the current filename. You need to have the SP SGML system ( installed in order to use this feature.
    sp_command_line = /usr/bin/nsgmls {$filename}
Set to 1 to force rebuild of the document title cache.
    forcecache = 0
Set to 1 to display help message.
    help = 0
Name of log file.
    log_file = mysite.log
Set to 1 to only process files added or changed since last release.
    update = 0
Set to 1 to upload processed files via FTP.
    upload = 0
Set to 1 to update the timestamp in the release file.
    release = 0
Set to 1 to validate processed files using the validator specified in sp_command_line.
    validate = 0
Set to 0, 1 or 2 to select the verbosity of the output. 0 for no output, 1 for normal output and 2 for debug messages.
    verbose = 1

Commandline options

-c, –config=name
Read settings from name.cfg.
Force cache rebuild.
-f, –ftp, –upload
Upload processed files via FTP.
-?, –help
Print this message
-l, –log[=filename]
Log names of processed HTML files.
-u, –update
Only process added or changed files.
-r, –release
Update timestamp in release file.
-v, –validate
Validate processed files with the nsgmls parser.
Set verbosity level of the script (n=[0..2]).

Template functions

The following functions are available in the templates:

Include another file in the template. The file is treated as a template.
Include another file in the template. The contents of the file are included without any processing.

Template variables

The following variables are available in the templates:

The subpages of the current page. Each element in this array is a reference to a hash with two keys: name and href. Name is the title of the page and href is the relative path to the page.
The breadcrumb trail leading to the current page. Each element in this array is a reference to a hash with two keys: name and href. Name is the title of the page and href is the relative path to the page.
FIXME describe @siblings
The absolute path to the site root. Makes it easier to link to the home page, global image directories etc.
The depth of the current page in the site structure. The root page has a depth of 0. Use this to turn page elements on or off at certain depths in the site structure.
The URL of the current page.
The relative path to the site root. Makes it easier to link to the home page, global image directories, etc.
The time just before the source file is sent to the template system.
The title of the current HTML source file (actually, the content of the first set of <h1> tags in the file). If no title can be found in the document, a default title is used.
Contains full paths to all templates found in the path of the current source file. Keys are the template files’ basenames.


Morten Wulff, <>


Copyright 2003, Morten Wulff

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the file “FDL”.

User Guide