aphra - Simple static sitebuilder in Perl
$ aphra build
aphra is a simple static sitebuilder written in Perl. It takes a directory tree of input template, processes them using the Template Toolkit and outputs a directory tree of expanded templates.
aphra has two command modes.
Examines the files in the input directory, processes them in various ways and leaves the processed version in the output directory.
See most of the rest of this documentation for the gory details.
Starts a local HTTP server which serves the files currently in the output directory.
You need to have App::HTTPThis installed in order for this to work.
aphra takes a number of command line options which alter the way that it works.
The main directory that contains the input files. Any file that is found in this directory will be processed and an equivalent output file will be created in the target directory. The default value for this option is "in".
$ aphra --in some/other/directory
A directory that contains other templates which are used in the processing of the source templates. For example, you might have a template in the source directory called
index.html.ttwhich includes other templates called
footer.html.tt. These templates shouldn't be put in the source directory (as they would then be processed and written to the target directory, but if they are put in the fragments directory, they will be found by the template processor. The default value for this option is "fragments".
$ aphra --fragments some/directory/of/fragments
A directory that contains templates which are used to control the layout of the files which are produced. These are typically used with the
WRAPPERdirective in the Template Toolkit. There's really no difference in handling the layouts and fragments directories, but I find it useful to keep the two types of template separate. The default value for this option is "layouts".
$ aphra --layouts some/directory/of/layouts
The name of a template that will be used as the main
WRAPPERfor the rest of the templates. This template should usually contain a
[% content %]tag and will normally be stored in the layouts directory. See the "Template Toolkit" documentation for more details of the
WRAPPERdirective. The default value for this option is "page".
$ aphra --wrapper my_awesome_layout
The name of the top-level directory where the output files will be written. Any directory structure under the source directory will be recreated under this directory. The default value for this option is "docs" (as that works well with Github pages).
$ aphra --target some/output/directory
The output format that pages will be created in. This can be any output format that
pandocunderstands. The default value is "html" and as long as you're creating web sites, there's going to be very little reason to change that.
$ aphra --output docx
Allows you to configure the extensions that are recognised as templates by the program. See "Processing Templates" below for more details of this. By default, templates with the extension
.ttare processed by the standard Template Toolkit processor and templates with the extension
.mdare converted from Markdown to the output format (see above) using
pandocbefore they are processed by the Template Toolkit.
Extensions options are more complex than other options. They consist of an extension string and the name of a text format as recognised by
pandoc. These two parts are separated by an equals sign. This option can be repeated in order to define multiple extensions.
$ aphra --extensions md=markdown --extensions tt=template
I've tried to make the template processing as simple as possible. Here's how it works.
The program finds all the files under the source directory. For each file it finds, it examines the extension of the file. If the extension doesn't match any of the defined extensions, then the file is copied to a mirror directory under the output directory.
If the extension does match one of the defined extensions, then one of two things is true.
The extension matches the special format "template". In this case, the template is just processed by the Template Toolkit.
The extension matches some other format name. In this case, the template is processed by
pandoc to convert the named format to the output format (html by default) before being processed by the Template Toolkit.
In both cases where the Template Toolkit is involved, the output file is placed under the output directory in a position that mirrors the position of the input file under the iput directory. The output file is also renamed to remove the extension that marked the input file as a template.
An example might make this clearer. Imagine we have all of the default configuration options and the following directory tree.
src/index.html.tt src/style.css src/about/index.html.tt fragments/index_text.md fragments/about_text.md
And assume that
index.html.tt includes the Template Toolkit directive
[% INCLUDE index_text.md %] and
about/index.html.tt contains a similar directive refering to
about_text.md. Here's what will happen.
src/index.html.ttis found. Its extension,
.tt, matches one of the defined extensions, so it is processed by the Template Toolkit.
As part of this processing, the Template Toolkit needs to process
index_text.md. This template is found in the fragments directory, but its extension,
.md, means that it is pre-processed by
pandoc(converting Markdown to HTML) before it is processed by the Template Toolkit.
The output from processing
src/index.html.ttis written to
.ttextension is removed.
src/style.cssis found. As its extension is not one of the defined ones, it is simply copied to
src/about/index.html.ttis found. It is processed in a very similar way to
src/index.html(including the processing of
fragments/about_text.mdand the output is written to
After the processing is complete, we have the following in the
docs/index.html docs/style.css docs/about/index.html
Dave Cross <email@example.com>
Copyright (c) 2017, Magnum Solutions Ltd. All Rights Reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.