Quick Start Guide

DESCRIPTION

Download Yggdrasil

Download the latest version of Yggdrasil: http://www.psyke.org/yggdrasil/

Install required Perl modules

Yggdrasil uses the following modules which are not included in the standard Perl distribution:

AppConfig

Date::Format (part of TimeDate)

Text::Template

You can download the modules from CPAN or Activestate’s package repository.

Create directories to store your site’s source files. These directories will contain your stripped HTML files, template files and all other files that are needed for your site (e.g. images and pdf files). For best results, create subdirectories for each content area, e.g.:

    mysite_source/
        about/
        essays/
            planes/
            trains/
            automobiles/
        contact/

Your HTML files should only contain a minimum of markup, though you are free to use any markup that is allowed inside <body> tags. All HTML files must contain at least one set of <h1> tags.

The text in the first set of <h1> found in a file is used to create the site navigation.

The contact page for the site above would be named index.html, be placed in the contact/ directory and could look like:

    <h1>Contact Me</h1>
    <p>
        You can reach me at this address: me@mysite
    </p>

By default, files named index.html or index.shtml are used to create the site navigation. This can be changed by editing the configuration file.

You can use HTML files which are not named index.html or index.shtml, but you must manually create links to them. To add a map page called map.html to the example above, we would create the file map.html in contact/ and edit index.html:

    <h1>Contact Me</h1>
    <p>
        You can reach me at this address: me@mysite
        <a href="map.html">Here is a map</a>.
    </p>

If you don’t want to handle the link to your map manually, you can create the directory contact/map/ and move map.html to contact/map/index.html. This will make the map show up in the autogenerated navigation.

Create templates

Templates are parsed with the Text::Template module. A basic template contains the HTML header and content that should be included on all pages of your site. The basic template for your site is called base.tmpl (the line numbers are not part of the template):

     1: <html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en">
     2: <head><title>My Site - {$title}</title></head>
     3: <body>
     4: <p>
     5:     You are here:
     6:     {
     7:         foreach my $item (@trail) {
     8:             if ($item->{href}) {
     9:                 $OUT .= qq(
    10:                     <a href="$item->{href}">$item->{name}</a> &gt;
    11:                 );
    12:             }
    13:             else {
    14:                 $OUT .= $item->{name};
    15:             }
    16:         }
    17:     }
    18: </p>
    19: {
    20:     if (@navigation) {
    21:         $OUT .= '<ul>';
    22:
    23:         foreach my $item (@navigation) { 1:
    24:             $OUT .= qq(
    25:                 <li><a href="$item->{href}">$item->{name}</a></li>
    26:             );
    27:         }
    28:
    29:         $OUT .= '</ul>';
    30:     }
    31:     else {
    32:         $OUT .= '';
    33:     }
    34: }
    35: {include_text($template{'__file__'})}
    36: </body>
    37: </html>

Line 1

Document type definition.

Line 2

Document title. {$title} inserts the title of the current source HTML file.

Line 4-18

Creates a breadcrumb trail. On the essays/trains/ page in the example site above, this would look like:

    Home > Essays > Trains.

Line 19-34

Creates navigation for all subpages of the current page.

Line 35

Inserts the content of the current source HTML file.

Line 36-37

Closes the HTML document.

It is possible to include templates in other templates. If you use the same footer in all you templates, you can place it in the file footer.tmpl and include it when you need it:

    {include($template{'footer.tmpl'})}

Yggdrasil searches the path to the current source file for templates. If you put footer.tmpl in mysite_source/ and an edited version of footer.tmpl in mysite_source/essays/, all the essay files will use the edited footer while the rest of the site will use the footer in the site root. Use this feature to create different looks for different parts of your site.

Variables

The following variables are available in the templates:

@navigation: 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.
@trail: 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.
$base_url: The absolute path to the site root. Makes it easier to link to the home page, global image directories etc.
$depth: 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.
$location: The URL of the current page.
$rel_path: The relative path to the site root. Makes it easier to link to the home page, global image directories, etc.
$timestamp: The time just before the source file is sent to the template system.
$title: 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.
%template: Contains full paths to all templates found in the path of the current source file. Keys are the template files’ basenames.

Functions

The following functions are available in the templates:

include ($filename): Include another file in the template. The included file is treated as a template.
include_text ($filename): Include another file in the template. The contents of the file are included without any further processing.

Create configuration file

You can either modify the included default.cfg or create your own. You only need to configure three parameters:

    input_dir  = /home/me/mysite_source
    output_dir = /home/me/wwwroot
    base_url   = http://www.mysite.com

This configuration file tells Yggdrasil to process the source files in /home/me/mysite_source and write the output files to /home/me/wwwroot. http://www.mysite.com is passed to the template variable $base_url.

Go!

Run y.pl:

    perl y.pl

    ./y.pl

depending on your OS and system setup.

Run

    perl y.pl --help

for a list of commandline options.

AUTHOR

Morten Wulff, <wulff@psyke.org>

COPYRIGHT

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”.