view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

   such as Perl, Python, or Ruby, all are more susceptible to being hacked
   than a static website is.  Simply stated, why use a dynamic content-
   management system if a static setup will do?

4. **Portable**. With a static website, it's way easier to move the site
   to a new host in the future. All web hosts now and in the future
   support serving up a static website -- think of it as the lowest common
   denominator -- and so there's no need to pick a premium host with
   premium services.

Dapper was first written in 2002 to facilitate the creation of a series
of static websites that each had their own look and feel, but shared
content. Since then, Dapper has been used to create websites for speakers,
artists, authors, illusionists, web designers, piano tuners,
photographers, entertainment agencies, and API documentation for
industrial sensing equipment. For many years it was also the tool that
powered the author's personal website.

In 2014, Dapper was submitted as a Perl module (App::Dapper) to
[CPAN](http://cpan.org/) under the MIT license for anyone to use for any
purpose.

**Features**

* Written in perl, available as a command line utility after installing.
* Content is written in Markdown.
* Layouts are developed using TT3 from the Template::Alloy templating engine.
* Configuration files and attributes are encoded with YAML.

The rest of this document shows you how to get your site up and running,
how to manage the content and the way it looks, and how to deploy the
result to your favorite web host.

**Contents**

* [Getting Started](#getting-started)
    * [Install](#install)
    * [Usage](#usage)
    * [Directory Structure](#directory-structure)
* [Tutorial: Build a Blog](#tutorial-build-a-blog)
* [Configuration](#configuration)
* [Source](#source)
    * [Source file types](#source-file-types)
    * [Assets](#assets)
    * [Drafts and clean builds](#drafts-and-clean-builds)
    * [Headings](#headings)
    * [Text](#text)
    * [Lists](#lists)
    * [Tables](#tables)
    * [Images](#images)
    * [Footnotes](#footnotes)
* [Layout](#layout)
    * [Variables](#variables)
    * [Comments](#comments)
    * [Filters](#filters)
    * [Conditionals](#conditionals)
    * [Iteration](#iteration)
    * [Blocks](#blocks)
    * [Perl code](#perl-code)
    * [Includes](#includes)
    * [Macros](#macros)
    * [Plugins](#plugins)
    * [Chomping](#chomping)
    * [Dumping](#dumping)
* [Deployment](#deployment)
    * [Amazon S3](#amazon-s3)
    * [GitHub Pages](#github-pages)
* [What Dapper Doesn't Do](#what-dapper-doesnt-do)
* [Upgrading from 0.21](#upgrading-from-021)
* [Troubleshooting](#troubleshooting)
* [Further Reading](#further-reading)
* [Appendix A: Extending](#appendix-a-extending)
* [Appendix B: Debugging](#appendix-b-debugging)
* [Appendix C: Internals](#appendix-c-internals)
* [Appendix D: Contributing](#appendix-d-contributing)
* [Author](#author)
* [License and Copyright](#license-and-copyright)

# Getting Started

The following sections show you how to install, upgrade, and downgrade the
version of Dapper you have, as well as how to use the `dapper` command-
line utility and work with the directory structure it depends on.

## Install

Dapper needs Perl 5.10 or newer. Check with `perl -v`. It is installed
with `cpanm`; if you don't have it, install it first:

    $ curl -L https://cpanmin.us | perl - App::cpanminus

On macOS, the Perl that comes with the system is best left alone. Rather
than installing modules into it with `sudo`, install your own Perl with
[Homebrew](https://brew.sh/) (`brew install perl`) or
[perlbrew](https://perlbrew.pl/), or install modules into your home
directory with [local::lib](https://metacpan.org/pod/local::lib).

Install Dapper in seconds:

    $ cpanm App::Dapper

Then, create a new site, build it, and view it locally like so:

    $ mkdir new-site && cd new-site
    $ dapper init
    $ dapper build
    $ dapper serve

After that, browse to [http://localhost:8000](http://localhost:8000) to
see your site.  To modify the content, look at `_source/index.md`. To
modify the layout, edit `_layout/index.html`.

### Upgrade

Find out which version of Dapper you have, by using the `-v` option:

    $ dapper -v

You can compare this with the latest version from CPAN like this:

    $ cpan -D App::Dapper

README.md  view on Meta::CPAN

    [% a = "Apple" %]
    [%~ PERL %]
        my $a = "[% a %]";
        print "The variable \$a is \"$a\"";
        $stash->set('b', "Banana");
    [% END %]
    [% b %]

This would print the following:

    The variable $a is "Apple"
    Banana

During execution, anything printed to STDOUT will be inserted into the
template. Also, the $stash and $context variables are set and are references
to objects that mimic the interface provided by Template::Context and
Template::Stash. These are provided for compatibility only. $self contains
the current Template::Alloy object.

The `rawperl` block can be used as well. It operates the same as the `perl`
block does except that you will need to append to the $output variable rather
than just calling `print`.

## Includes

An `include` directive parses the contents of a file or `block` and inserts them
into the template. File names are relative to the layout directory
(`_layout`), so shared pieces such as a header or footer can live there
next to the layouts (e.g. `_layout/include-footer.html`, included with
`[% include "include-footer.html" %]`). Every file in the layout directory
can also be used as a layout, so give partials a name that makes their
purpose clear. Variables that are defined or modified within the included
bits are discarded after the include occurs. Example:

    [% include "path/to/template.html" %]

    [% file = "path/to/template.html" %]
    [% include $file %]

    [% block foo %]This is foo[% end %]
    [% include foo %]

Arguments may also be passed to the template:

    [% include "path/to/template.html" a = "An arg" b = "Another arg" %]

Multiple filenames can be passed by separating them with a plus, a space, or 
commas. Any supplied arguments will be used on all templates. Example:

    [% include "path/to/template1.html",
               "path/to/template2.html" a = "An arg" b = "Another arg" %]

If it's important that the included file *not* be parsed for directives, an
alternative directive may be used called `insert`. `Insert` directives act in
exactly the same way that `include` directives do, but does not process any 
directives that the inserted file might contain. Example:

    [% insert "path/to/template1.html",
              "path/to/template2.html" %]

## Macros

The `macro` directive can be thought of as a way to define a miniature function
that can be used elsewhere in the template. Example:

    [% macro foo(i, j) block %]You passed me [% i %] and [% j %].[% end %]
    [% foo(1, 2) %]

Result:

    You passed me 1 and 2.

Another example:

    [% macro bar(max) foreach i = [1 .. max] %]([% i %])[% end %]
    [% bar(4) %]

Result:

    (1)(2)(3)(4)

## Plugins

Layout plugins provide a way to get access to special functionality that are 
more complicated than what [filters](#filters) provide. This section defines some 
of the plugins that are distributed with Dapper. For a comprehensive list, see 
[Template::Toolkit plugin](http://template-toolkit.org/docs/manual/Plugins.html).

### Datafile

This plugin provides a simple facility to construct a list of hash references, 
each of which represents a data record of known structure from a specified data 
file. A filename must be specified. An optional delim parameter may also be 
provided to specify an alternate delimiter character.

The format of the file is intentionally simple. The first line defines the field 
names, delimited by colons with optional surrounding whitespace. Subsequent lines 
then defines records containing data items, also delimited by colons. For example:

    id : name
    mdb: Mark Benson
    lkb: Loomis Buschwa

Each line is read, split into composite fields, and then used to initialize a 
hash array containing the field names as relevant keys. The plugin returns a 
blessed list reference containing the hash references in the order as defined in 
the file. Example:

    [% use userlist = datafile('users.txt', delim = ':') %]
    [% for user in userlist %]
        [% user.id %] -> [% user.name %]
    [% end %]

Result:

    mdb -> Mark Benson
    lkb -> Loomis Buschwa

The first line of the file must contain the field definitions. After the first 
line, blank lines will be ignored, along with comment line which start with a '#'.