The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
StaticVolt-1.00
River stage zero No dependents
1 ++
/ StaticVolt

NAME

StaticVolt - Static website generator

VERSION

version 1.00

SYNOPSIS

    use StaticVolt;

    my $staticvolt = StaticVolt->new;  # Default configuration
    $staticvolt->compile;
new

Accepts an optional hash with the following parameters:

    # Override configuration (parameters set explicitly)
    my $staticvolt = StaticVolt->new(
        'includes'    => '_includes',
        'layouts'     => '_layouts',
        'source'      => '_source',
        'destination' => '_site',
    );

  • includes

    Specifies the directory in which to search for template files. By default, it is set to _includes.

  • layouts

    Specifies the directory in which to search for layouts or wrappers. By default, it is set to _layouts.

  • source

    Specifies the directory in which source files reside. Source files are files which will be compiled to HTML if they have a registered convertor and a YAML configuration in the beginning. By default, it is set to _source.

  • destination

    This directory will be created if it does not exist. Compiled and output files are placed in this directory. By default, it is set to _site.

compile

Each file in the "source" directory is checked to see if it has a registered convertor as well as a YAML configuration at the beginning. All such files are compiled considering the "YAML Configuration Keys" and the compiled output is placed in the "destination" directory. The rest of the files are copied over to the "destination" without compiling.

YAML Configuration Keys

"YAML Configuration Keys" should be placed at the beginning of the file and should be enclosed within a pair of ---.

Example of using a layout along with a custom key and compiling a markdown "source" file:

"layout" file - main.html:

    <!DOCTYPE html>
    <html>
        <head>
            <title></title>
        </head>
        <body>
            [% content %]
        </body>
    </html>

"source" file - index.markdown:

    ---
    layout: main.html
    drink : water
    ---
    Drink **plenty** of [% drink %].

"destination" (output/compiled) file - index.html:

    <!DOCTYPE html>
    <html>
        <head>
            <title></title>
        </head>
        <body>
            <p>Drink <strong>plenty</strong> of water.</p>

        </body>
    </html>

  • layout

    Uses the corresponding layout or wrapper to wrap the compiled content. Note that content is a special variable used in Template Toolkit along with wrappers. This variable contains the processed wrapped content. In essence, the output/compiled file will have the content variable replaced with the compiled "source" file.

  • custom keys

    These keys will be available for use in the same page as well as in the layout. In the above example, drink is a custom key.

Pre-defined template variables

Some variables are automatically made available to the templates. Apart from content described elsewhere, these are all prefixed sv_ to differentiate them from user variables.

sv_rel_base

If the generated web-site is being used without a web-server (i.e. just on the local file-system), or perhaps if it may be moved around in the web-server hierarchy, then absolute URIs to shared resouces like CSS or JS will not work.

Relative paths can be used in these situations.

sv-rel-base provides a relative path from the source file being processed to the top of the generated web-site. This means that layout files can refer to shared files like CSS using the following in a layout file:

    <link rel="stylesheet" type="text/css" href="[% sv_rel_base %]css/bootstrap.css" />

For top level source files, this expands to ./. For any sub-directories, it expands to ../, ../../ etc. Sub-directory expansions always include the trailing slash.

Walkthrough

Consider the source file index.markdown which contains:

    ---
    layout : main.html
    title  : Just an example title
    heading: StaticVolt Example
    ---

    StaticVolt Example
    ==================

    This is an **example** page.

Let main.html which is a wrapper or layout contain:

    <!DOCTYPE html>
    <html>
        <head>
            <title>[% title %]</title>
        </head>
        <body>
            [% content %]
        </body>
    </html>

During compilation, all variables defined as "YAML Configuration Keys" at the beginning of the file will be processed and be replaced by their values in the output file index.html. A registered convertor (StaticVolt::Convertor::Markdown) is used to convert the markdown text to HTML.

Compiled output file index.html contains:

    <!DOCTYPE html>
    <html>
        <head>
            <title>Just an example title</title>
        </head>
        <body>
            <h1>StaticVolt Example</h1>
            <p>This is an <strong>example</strong> page.</p>

        </body>
    </html>

Default Convertors

How to build a convertor?

The convertor should inherit from StaticVolt::Convertor. Define a subroutine named "convert" in StaticVolt::Convertor that takes a single argument. This argument should be converted to HTML and returned.

Register filename extensions by calling the register method inherited from StaticVolt::Convertor. register accepts a list of filename extensions.

A convertor template that implements conversion from a hypothetical format FooBar:

    package StaticVolt::Convertor::FooBar;

    use strict;
    use warnings;

    use base qw( StaticVolt::Convertor );

    use Foo::Bar qw( foobar );

    sub convert {
        my $content = shift;
        return foobar $content;
    }

    # Handle files with the extensions:
    #   .foobar, .fb, .fbar, .foob
    __PACKAGE__->register(qw/ foobar fb fbar foob /);

Inspiration

StaticVolt is inspired by Tom Preston-Werner's Jekyll.

Success Stories

Charles Wimmer successfully uses StaticVolt to generate and maintain his website. He describes it in his post.

If you wish to have your website listed here, please send an e-mail to haggai@cpan.org, and I will be glad to list it here. :-)

Contributors

Gavin Shelley

Acknowledgements

Shlomi Fish for suggesting change of licence.

See Also

Template Toolkit

AUTHOR

Alan Haggai Alavi <haggai@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2013 by Alan Haggai Alavi.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)