Manpage of swtk(1)

NAME

swtk - generate HTML files from simple Markdown files and templates

SYNOPSIS

DESCRIPTION

This static website toolkit uses files in a Markdown format and template files to generate HTML files automatically. This helps to maintain or create a website, as the content can be written without being too concerned about markup.

swtk uses the Perl modules Text::Template and Text::Markdown for parsing, so they have to be installed first.

The program parses several input files, collects all necessary information and generates the HTML files afterwards. So most attention should be paid on the structure of the input files (see files section for details). Mandatory is a configuration file.

Basically you need

an input directory containing .swtk files (default swtk-data/)

a template directory containing .tmpl files (default templates/)

at least one template file (default default.tmpl)

an output directory (default data/)

a configuration file

But also precedence is important: all your definitions made in the configuration file can be changed by calling swtk with the specific option and/or by an entry in the .swtk file.

OPTIONS

At least the configuration file has to be set.

It is recommended to specify all the options there, but you can use the option parameters to overwrite the settings made in your configuration.

-c, --config name.cfg

Specify which configuration file should be used.

-i, --input-dir dirname

Set the input directory.

-o, --output-dir dirname

Set the output directory.

-t, --template-dir dirname

Set the directory where the templates are located.

-d, --template-default filename

Set the file to use as default.

-e, --ext .extension

Change the input files' extension, if it is not .swtk as default.

-s --sitemap

A sitemap (sitemap.xml) will be generated or removed.

--clean

Removes all generated HTML files and the sitemap and empty directories beneath the output directory. It has to be used with either a configuration file or the input and output directory parameter to determine the files to be cleaned. (See cleaning up for an example.)

-v, --verbose

Gives a little more information on what is going on.

-h, --help

Shows a help text.

FILES

configuration.cfg

The configuration file takes all the information needed to run the program to your definitions: input and output directory, sitemap, ... If nothing is set swtk takes the default settings. But you can also define variables that can be used in the template such as path to css files, year, author, ...

example.cfg

The following variables have to be set:

 SITE_NAME      =       Your Website
 SITE_URL       =       http://www.some.were.com/
 SITE_AUTHOR    =       Your name

Those have to be set, if you do not want to use the default values:

 TEMPLATE_DIR   =       templates/
 TEMPLATE_DEFAULT=      my_template.tmpl
 DIR_INPUT      =       website
 DIR_OUTPUT     =       website-html
 VERBOSE        =       1
 SITEMAP        =       1
 SITEMAP_STYLE  =       "/sitemap.xsl"
 SITEMAP_IGNORE =       "disclaimer" # use a Perl regular expression here

Feel free to add more variables, for example:

 CSS_FILE       =       my_style.css
 YEAR           =       2008

swtk-data/my_site.swtk

The .swtk files contain the content of your website. At first you might specify variables that will be interpolated afterwards. If the same variables were already set in the configuration file, they will be overwritten.

The content has to be written in markdown syntax: see http://daringfireball.net/projects/markdown/. This is a simple to use and read markup but you can also use HTML syntax where necessary or appreciated.

example.swtk

 TITLE          = site's title  
 KEYWORDS       = these words decribe it best  
 TEMPLATE       = other-than-default.tmpl  


 # Heading #

 My text, that will be converted to **HTML**.

 <table>  
 <tr><td> tables are not supported by Text::Markdown
          so use HTML here.</td></tr>
 </table>

The variables will be interpolated in the template afterwards. The TEMPLATE variable overwrites the setting made in the configuration file. The rest of the file is just your content. The heading is for example translated to <h1></h1>, **HTML** to <strong>HTML</strong> by Text::Markdown.

templates/default.tmpl

The template defines the structure of the HTML page as such. You can use HTML code, put all your variables where they belong and even embed Perl code. The template is used by Text::Template so you may read this manpage for further details.

example.tmpl

 <html>
  <head>
    <title>{$TITLE}</title>

    <meta name="author" content="{$AUTHOR}">
    <meta name="keywords" content="{$KEYWORDS}">

    <link rel="stylesheet" type="text/css" href="layout.css" />
  </head>

  <body>

    {$CONTENT}

  </body>
 </html>

The structure of the site is defined in this template for all your documents and the variables will be set according to your configuration or .swtk files.

Beside that, the following variables are passed to all templates:

PAGE_URL

The relative URL of the resulting output document.

FILENAME

The path to the swtk file being processed.

CONTENT

The .swtk file's content in HTML, as processed by Text::Markdown.

data/my_site.html

The HTML files will be generated automatically. If no directory is specified swtkl creates a directory (data/) to put the files in.

EXAMPLES

For displaying some examples the following structure is assumed:

        templates/default.tmpl
                  start.tmpl
        website/start.swtk
                important.swtk
                contact.swtk
        website-html/
        swtk-data/index.swtk
                  topic.swtk
        my_configuration.cfg
        swtk.pl

using a configuration file

• The configuration file has the settings from example.cfg.
• There are two templates: the default template is for all the content pages and the start page should look different.
• To use the start template, the file website/start.swtk sets the variable TEMPLATE = start.tmpl.

                user@work:$ swtk.pl -c my_config.cfg 

                Reading configuration from my_config.cfg...
                001/003: website/start.swtk
                002/003: website/important.swtk
                003/003: website/contact.swtk
                Processed 3 input files.
                Generating sitemap.xml... 3 entries.

According to the configuration file, the directory website/ is taken as input, a sitemap is generated and the program runs in verbose mode. After running swtk the output directory contains the following files:

        website-html/start.html
                     important.html
                     contact.html
                     sitemap.xml

using a different input and output directory

If your templates and all the other settings are fine, but you are working on a different website, you can change the input and output directory:

        user@work:$ swtk.pl -c my_config.cfg -i swtk-data/ -o data/

        Reading configuration from my_config.cfg...
        001/002: swtk-data/index.swtk
        002/002: swtk-data/topic.swtk
        Processed 2 input files.
        Generating sitemap.xml... 2 entries.

Now the settings from the configuration file were overwritten with the commandline parameters and the files from swtk-data/ were taken as input. The output files are stored in data/, which will be created.

        data/index.html
             topic.html

cleaning up

To remove the generated HTML files and the sitemap say

        user@work:$ swtk.pl -c my_config.cfg --clean

        Reading configuration from my_config.cfg...
        Removing website-html/start.html...
        Removing website-html/important.html...
        Removing website-html/contact.html...
        Removing website-html/sitemap.xml...
        Removed 4 files and 0 directories.

The configuration file has to be called so that --clean knows, what to clean (the files to clean are determined by examining the content of the input directory). So if you want to delete the files you generated beside those specified in the configuration file type

        user@work$ swtk.pl -i swtk-data/ -o data/ --clean

        Removed 2 files and 0 directories.

As the configuration file is not called, the output is not verbose this time.

BUGS

None known so far.

Please report bugs to alex@use-strict.de

SEE ALSO

the Text::Template manpage

the Text::Markdown manpage

AUTHOR

Software: Alex Linke <alex@use-strict.de>

Documentation: Rona Linke <rona@schnatterblog.de>

COPYRIGHT AND LICENSE

Copyright (c) 2008, Alex Linke and Rona Linke. All rights reserved.

This module is free software. It may be used, redistributed and/or modified under the terms of the BSD license.