Templer
=======
Templer is yet another static site generator, written in Perl.
It makes use of the
[HTML::Template](http://search.cpan.org/perldoc?HTML%3A%3ATemplate) module for
performing variable expansion within pages and layouts, along with looping and
conditional-statement handling.
Templer has evolved over time for my own personal use, but I believe
it is sufficiently generic it could be useful to others.
My motivation for putting it together came from the desire to change
several hand-made, HTML-coded, sites to something more maintainable such
that I could easily change the layout in one place.
The design evolved over time but the key reason for keeping it around
is that it differs from many other simple static-generators in several
ways:
* You may define global variables for use in your pages/layouts.
* A page may define and use page-specific variables.
* You may change the layout on a per-page basis if you so wish.
* This was something that is missing from a lot of competing tools.
* Conditional variable expansion is supported, via `HTML::Template`.
* File contents, shell commands, and file-globs may be used in the templates
* This allows the trivial creation of galleries, for example.
* These are implemented via plugins.
* Plugins are documented in the file [PLUGINS.md](PLUGINS.md).
* You may also embed perl code in your pages.
Another key point is that the layouts allow for more than a single
simple "content" block to be placed into them - you can add arbitrary
numbers of optional side-menus, for example.
Although this tool was written and used with the intent you'd write your
site-content in HTML you can write your input pages in Textile or Markdown
if you prefer (these inputs are supported via [plugins](PLUGINS.md)).
Concepts
--------
A templer site comprises of three things:
* A global configuration file.
* This defines the paths to search for input pages, layout templates, plugins, etc.
* This may contain global variable declarations.
* Please see the example configuration file:
[`templer.cfg`](https://raw.github.com/skx/templer/master/templer.cfg.sample).
* A layout.
* This is used to format the output pages, defining the common look and feel.
* A series of pages & assets.
* Pages have their content processed and inserted into the layout to produce output HTML.
* Assets are not processed, but are copied into the output directory literally.
In general we assume there is a tree like so:
├── input
│ ├── index.wgn
│ ├── ...
│ ├── ...
│ ├── favicon.ico
│ └── robots.txt
├── layouts
│ └── default.layout
├── output
└── templer.cfg
Every file in the input directory is either considered to be a page which is converted
into HTML, or an asset which is copied into the output-tree with no changes made.
In the example above `input/index.wgn` would become `output/index.html`.
> **NOTE** The `.wgn` suffix is an example. You can define which suffix is considered a page via the configuration file.
There is _also_ an "in-place" mode. When working in-place there is no
distinct output directory, instead output is written to the same directory in
which is encountered. Given an input directory you might see this kind of
transformation:
index.wgn -> index.html
about.wgn -> about.html
favicon.ico [Ignored and left un-modified.]
robots.txt [Ignored and left un-modified.]
..
There is _also_ a *synchronized* mode. When working synchronized any file in
the output directory which do not have a source file in input directory (page
or asset) is removed each time the site is rebuild.
Pages
-----
Your site will be made of pages, which are snippets of HTML you write. These
snippets will be processed and inserted into the layout file before being output
to disk.
A page is a simple file which contains a header and some content. This is
a sample page:
Title: This is the title page.
----
<p>This is the body of the page</p>
The header of the page is delimited from the body by four dashes (`----`) and
can contain an arbitrary number of variable definitions.
Special Page Variables
-----------------------
In your page you can define, and refer to, an arbitrary number of variables
but some names are reserved - and any variable with one of those names will
be treated specially:
The special variable `layout` may be used to specify a different layout
template for the current page. If there is no per-page layout specified then
the global layout declared in the `templer.cfg` file will be used.
The special variable `template-filter` may be used to specify some filters to
apply on the used layout in order to transform it into valid `HTML::Template`
file. If there is no per-page layout filter specified then the global layout
declared in the `templer.cfg` file will be used.
The special variable `output` may be used to specify an alternative output
file. For example the input file `index.wgn` would normally become
`index.html`, but you could make it become something else.
The special variable `format` may be given a value of `textile`, `markdown`, or
`perl` to enable processing the page body with the appropriate filter. These
formatters are implemented as [plugins](PLUGINS.md), and will be available
assuming their [dependencies are installed](#installation).
Textile and markdown are well-known, and allow you to write your page content naturally. The perl-formatter is used to allow you to write dynamic content in Perl in your page-body, via the [Text::Template](http://search.cpan.org/perldoc?Text%3A%3ATemplate) module. Perl code to be executed is wrapped in `{` and `}` characters. Here is a sample page:
Title: This page has code in it
format: perl
----
<p>This page has some code in it.</p>
<p>I am running on { `hostname` }...</p>
<p>I am {
my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
localtime(time);
$year += 1900;
$year - 1976;
} years old.</p>
> **NOTE**: Formatters may be chained. For example "`format: perl, markdown`".
Variable Definitions
--------------------
Within the header of each page you may declare an arbitrary number of per-page
variables. These variable declarations are then available for use within the
page-body, using the standard [HTML::Template](http://search.cpan.org/perldoc?HTML%3A%3ATemplate) expansion facilities:
Title: Page title
Name: Steve Kemp
----
<p>Hello, my name is <!-- tmpl_var name='name' -->.</p>
> **NOTE**: All variable-names are transformed to lower-case for consistency, which is why we refer to the variable `name` rather than the defined `Name`.
As well as simple "name: value" pairs there are also additional options implemented in [plugins](PLUGINS.md);
* A variable may refer to the contents of a given file.
* Using `read_file`.
* A variable may refer to a list of filenames, matching a pattern.
* Using `file_glob`.
* A variable may contain the output of running a command.
* Using `run_command`.
* A variable may be based on the timestamp of the input page.
* Using `timestamp`.
* A variable may contain the contents of a remote RSS feed.
* Using `rss(count, URL)`.
* A variable may contain the result of a key-lookup from a Redis server.
* Using `redis_get('foo')`.
In addition to declaring variables in a page-header you may also declare
__global__ variables in your `templer.cfg` file, or upon the command-line
via `--define foo=bar`.
Defining global variables is demonstrated in the sample [`templer.cfg`](https://raw.github.com/skx/templer/master/templer.cfg.sample) file.
File Globbing Variables
-----------------------
We've already seen simple variables declared by `key: value` in the page header,
in addition to this you may define a variable that refers to a number of files
by pattern.
Here is a simple example of creating a gallery which will include files matching
the pattern `img/*.jpg`:
Title: My gallery
Images: file_glob( "img/*.jpg" )
---
<!-- tmpl_if name='images' -->
<!-- tmpl_loop name='images' -->
<p><img src="<!-- tmpl_var name='file' -->"
height="<!-- tmpl_var name='height' -->"
width="<!-- tmpl_var name='width' -->" /> </p>
<!-- /tmpl_loop -->
<!-- tmpl_else -->
<p>No images were found.</p>
<!-- /tmpl_if -->
> **TIP**: If your images are numbered numerically you can ensure their correct order by doing this:
Title: This is my title
images: file_glob( img/[0-9].jpg img/1[0-9].jpg )
----
<p>My gallery is now included in ascending numerical order:</p>
This facility is implemented in the `Templer::Plugin::FileGlob` [plugin](PLUGINS.md).
The file glob is primarily designed for handling image-galleries, which is why it will set the `height` and `width` attributes if your glob matches `*.jpg`, `*.png`, etc. However it can also be used for non-images.
If your glob matches files which are not images it will populate the member `content`, being the text-content of the matching files. This allows you to include files easily. For example:
Title: This is my news-page
news: file_glob( news-*.txt )
----
<p>Here are the recent events:</p>
<!-- tmpl_loop name='news' -->
<p><!-- tmpl_var name='content' --></p>
<!-- /tmpl_loop -->
This assumes you have files such as `news-20130912.txt`, etc, and will show the contents of each file in (glob)order.</p>
If matching files are templer input files then all templer variables are populated instead of the text-content of the matching files.
In all cases it will populate `dirname`, `basename` and `extension`, being parts of each matching files name.
File Inclusion
--------------
The [HTML::Template](http://search.cpan.org/perldoc?HTML%3A%3ATemplate) module supports file inclusion natively, via the following construct:
<p>This is some text.</p>
<!-- tmpl_include name='/etc/passwd' -->
<p>That was my password file.</p>
In addition to this you may define a variable to contain the contents of a specified file. For example:
Title: This file has my passwords!
Passwd: read_file( "/etc/passwd" )
----
<p>Please see my passwords:</p>
<pre><!-- tmpl_var name='passwd' -->
</pre>
This facility is implemented in the `Templer::Plugin::FileContents` [plugin](PLUGINS.md).
Include files, whether included via the `read_file` method, or via the native HTML::Template faclity, are searched for in the same fashion:
* If the filename is fully-qualified, then the absolute path-name will be used.
* Otherwise the include-path will be searched.
* After the include-path has been searched the file will be looked for in the location relative to the input page location.
This allows you to place all your include-files in a single directory which is outside your web-root.
> **TIP**: The advantage of choosing to use `read_file` over the native HTML::Template support is that with the former the output page will be automatically rebuilt if you modify the include file.
Shell Command Execution
-----------------------
Pages may also define variables which receive the value of the output of shell commands. This is done via definitions like this:
Title: This file is dynamic
Host: run_command( "hostname" )
----
<p>This page was built upon <!-- tmpl_var name='host' -->.</p>
This facility is implemented in the `Templer::Plugin::ShellCommand` [plugin](PLUGINS.md).
Remote RSS Feeds
----------------
Pages may use snippets of RSS feeds, limiting them to the given
number of entries. For example:
title: About my site
feed: rss(4, http://blog.steve.org.uk/index.rss )
----
<p>This page is about my site, here are my recent blog posts:</p>
<ul>
<!-- tmpl_loop name='feed' -->
<li><a href="<!-- tmpl_var name='link' -->"><!-- tmpl_var name='title' --></a></li>
<!-- /tmpl_loop -->
</ul>
Redis Lookups
-------------
If you have a redis-server running upon the local system you may
configure page-variables to retrieve their values via lookups against it.
For example:
title: Site Statistics
count: redis_get( "global_count" )
----
<p>There are <!-- tmpL-var name='count' --> entries.</p>
Installation
------------
Templer is developed in a public fashion, here on github, but stable releases
are also uploaded to CPAN:
* [App::Templer](http://search.cpan.org/dist/App-Templer/)
Installation should be as simple as any other CPAN-based module:
$ git clone https://github.com/skx/templer.git
$ cd templer
$ perl Makefile.PL
$ make test
$ sudo make install
(If you ever wish to remove the software you may run `sudo make uninstall`.)
The code makes use of a reasonably large number of modules for its
implementation, and you can see a brief overview of [the logical structure](#object-hierarchy) later.)
If you want to get a standalone `templer` executable which includes all those `Templer` modules, you can use the `standalone` target of the generated `Makefile`:
$ make standalone
This will produce a script called `templer` in the base directory so that you should be able to use it alone without copying these used modules anywhere in perl library directories.
The dependencies are minimal, to ease installation:
* Perl
* The [Module::Pluggable](http://search.cpan.org/perldoc?Module%3A%3APluggable) module for loading plugins.
* The [HTML::Template](http://search.cpan.org/perldoc?HTML%3A%3ATemplate) module.
* This may be installed, on a Debian system, with `apt-get install libhtml-template-perl`.
* The following are optional modules:
* The [Image::Size](http://search.cpan.org/perldoc?Image%3A%3ASize) module is used if available whenever you create `file_glob`-using loops of image files.
* This will set the attributes `width` and `height` any images added via `file_glob`.
* The [Text::Markdown](http://search.cpan.org/perldoc?Text%3A%3AMarkdown) module is required if you wish to write your page bodies in Markdown.
* This may be installed, on a Debian system, with `apt-get install libtext-markdown-perl`.
* The [Text::Textile](http://search.cpan.org/perldoc?Text%3A%3ATextile) module is required if you wish to write your page bodies in Textile.
* This may be installed, on a Debian system, with `apt-get install libtext-textile-perl`.
* The [Text::Template](http://search.cpan.org/perldoc?Text%3A%3ATemplate) module is required if you wish to include dynamic perl in your input pages.
* This may be installed, on a Debian system, with `apt-get install libtext-template-perl`.
* The [Redis](http://search.cpan.org/perldoc?Redis) module is required if you wish to use the Redis plugin.
* This may be installed, on a Debian system, with `apt-get install libredis-perl`.
* The [XML::Feed](http://search.cpan.org/perldoc?XML%3A%3AFeed) module is required if you wish to use the RSS plugin.
* This may be installed, on a Debian system, with `apt-get install libxml-feed-perl`.
If you prefer you can install Debian binary packages from my personal repository:
* [templer repository for Debian GNU/Linux](http://packages.steve.org.uk/templer/)
Creating a new site
-------------------
There is a supplied script `templer-generate` which will create a new site-structure
if you give in the name of a directory to create & write to:
~$ templer-generate my-site
~$ tree my-site/
my-site/
├── include
├── input
│ ├── about.wgn
│ ├── index.wgn
│ └── robots.txt
├── layouts
│ └── default.layout
├── output
└── templer.cfg
If you prefer you may go through the process manually creating a directory,
adding the [`templer.cfg`](https://raw.github.com/skx/templer/master/templer.cfg.sample)
to it, and then creating the input tree and layout directory.
There are several [examples](examples/) provided with the distribution to illustrate the
software. These example sites are built automatically every evening and
uploaded online - so you may easily compare the input and the generated
output:
* [simple example source](https://github.com/skx/templer/tree/master/examples/simple)
* The online [generated output](http://www.steve.org.uk/Software/templer/examples/simple/output/).
* [complex example source](https://github.com/skx/templer/tree/master/examples/complex)
* The online [generated output](http://www.steve.org.uk/Software/templer/examples/complex/output/).
* The generated "complex" example is designed to be a standalone introduction to templer.
Rebuilding a site
-----------------
If you're beneath the directory containing your `templer.cfg` file simply
run `templer` with no arguments. You may optionally add flags to control
what happens:
* `templer --verbose`
* To see more details of what is happening.
* `templer --force`
* To force a rebuild of the site.
* `templer --define foo=bar`
* Define the variable `foo` for use in your templates. This will over-ride any setting of foo in the configuration file you've loaded.
In the general case `templer` should rebuild only the files which are needed
to be built. A page will be rebuilt if:
* The page source is edited.
* The layout the page uses is edited.
* Any include-file the page includes is edited.
* This applies to those includes read via [read_file](#file-inclusion) rather than via `HTML::Template` includes
> Previously it was required that you run `templer` from the top-level of your site, this has now changed. `templer` will walk upwards from the current working directory and attempt to find the site-root by itself.
Object Hierarchy
----------------
Although `templer` is distributed and used as a single script it is written
using a series of objects. Bundling into a single binary allows for easier
distribution, installation and usage.
In brief the control flow goes like this:
* `templer` runs, parses the command line, etc.
* A `Templer::Global` object is created to read the `templer.cfg` file, or the file passed via `--config=foo`.
* The options from the command-line and the config file are merged.
* From this point onwards `Templer::Global` is ignored.
* A `Templer::Site` object is created, using the merged config values.
* A `Templer::Timer` object is created to record the build-time.
* The build process is contained in `Templer::Site::build()`:
* A `Templer::Plugin::Factory` object is created to load plugins.
* A `Templer::Site::Page` object is created for each appropriate input.
* Each page is output.
* The plugins are unloaded.
* The assets are copied via `Templer::Site::copyAssets()`.
* The output directory is cleaned via `Templer::Site::sync()`.
* The build-time/build-count is reported and the process is complete.
Each of the modules has a simple test-case associated with it. To test functionality, especially after making changes, please run the test-suite:
$ make test
prove --shuffle t/
t/style-no-tabs.t ........................... ok
t/test-dependencies.t ....................... ok
..
..
t/test-templer-plugin-filecontents.t ........ ok
t/test-templer-site.t ....................... ok
t/test-templer-plugin-timestamp.t ........... ok
All tests successful.
Files=15, Tests=286, 1 wallclock secs ( 0.11 usr 0.01 sys + 0.88 cusr 0.14 csys = 1.14 CPU)
Result: PASS
Any test-case failure is a bug, and should be reported as such.
Problems
--------
Please report any issue via the github repository:
* https://github.com/skx/templer
Author
------
Steve Kemp <steve@steve.org.uk>