NAME

App::Dapper - A publishing tool for static websites.

VERSION

Version 1.00

SYNOPSIS

Dapper allows you to transform simple text files into static websites. By installing the App::Dapper Perl module, an executable named dapper will be available to you in your terminal window. You can use this executable in a number of ways:

# Initialize the current directory with a fresh skeleton of a site
$ dapper [-solc] init

# ...or with a complete starter blog
$ dapper init --template blog

# Build the site
$ dapper [-solc] build

# Serve the site locally at http://localhost:8000
$ dapper [-solcp] serve

# Rebuild the site if anything (source, layout dirs; config file) changes
$ dapper [-solc] watch

# Check the site for problems, without touching the output directory
$ dapper [-solc] check [--json]

# Build, check and publish the site (to S3, GitHub Pages, or a command)
$ dapper deploy [target] [--dry-run]

# Let AI assistants read, write, check and build the site over MCP
$ dapper -C /path/to/site mcp

# Get help on usage and switches
$ dapper -h

# Print the version
$ dapper -v

Additionally, Dapper may be used as a perl module directly from a script. Examples:

use App::Dapper;

# Create a Dapper object
my $d = App::Dapper->new();

# Initialize a new website in the current directory
$d->init();

# Build the site
$d->build();

# Serve the site locally at http://localhost:8000
$d->serve();

DESCRIPTION

Dapper helps you build static websites. To get you started, you can use the dapper init command to initialize a directory. After running this command, the following directory structure will be created:

_config.yml
_layout/
    index.html
_source/
    index.md

In that same directory, you may then build the site using the dapper build command, which will combine the source files and the layout files and place the results in the output directory (default: _output). After you build the default site, you'll then have the following directory structure:

_config.yml
_layout/
    index.html
_source/
    index.md
_output/
    index.html

To see what your website looks like, run the dapper serve command which will spin up a development webserver and serve the static files located in the output directory (default: _output) at http://localhost:8000.

Now, let's walk through each file:

_config.yml

The configuration file is a YAML file that specifies key configuration elements for your static website. The default configuration file is as follows:

---
name : My Site

If you want to use a separate source, layout, or output directory, you may specify it in this file. For instance:

---
name : My Site
source : _source
layout : _layout
output : _output

Directories given on the command line take precedence over the ones in the configuration file, which take precedence over the defaults.

All of the configurations in this file are available in layout templates under the site namespace. For instance, name in the configuration file may be used in a template as follows:

[% site.name %]
_source/index.md

A sample markdown file is available in the _source directory. Contents:

---
layout: index
title: Welcome
---

Hello world.

There are a few things to note about this file:

1. There is a YAML configuration block (the "front matter") at the start of the file.
2. The layout configuration specifies which layout to use.
3. The index layout indicates that _layout/index.html should be used.
4. The title configuration is the name of the post/page. It is optional.
5. All of the configurations may be used in the corresponding layout file.
<!-- Example use of "title" in a layout file -->
<h1>[% page.title %]</h1>

Files in the source directory that do not start with front matter (images, PDFs, plain text files and so on) are copied to the output directory as they are.

A page's content is not run as template code unless the page sets template: true; layouts always are. templates_in_content: true in _config.yml restores the behavior of Dapper before 1.0, where all content and _config.yml values were templates too.

A _schema.yml file in a source directory describes the front matter its pages must have; see App::Dapper::Schema. YAML and JSON files in _data are available as site.data.

_layout/index.html

Layout files are processed using the template language provided by Template::Alloy (the Template Toolkit mini-language). The initial layout file that is given after you run the dapper init command, is this:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>[% page.title %]</title>
</head>

<body>

[% page.content %]

</body>
</html>

The main content of the text file that is being rendered with this template is available using [% page.content %].

Definitions specified in the _config.yml file can be referenced under the "site" namespace (e.g. [% site.name %]). Definitions specified in the front matter of source files can be referenced under the "page" namespace (e.g. [% page.title %]).

_output/index.html

The output file that is created is a mix of the input file and the layout that is specified by the input file. For the default site, the following output file is created:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Welcome</title>
</head>

<body>

<p>Hello world.</p>

</body>
</html>

Variables

The following variables are available in layouts and source files.

site.*

Everything defined in _config.yml, plus:

site.time         The time the build started (a DateTime)
site.pages        Every page, in source path order
site.categories   A hash of category name to its pages, sorted by date
site.tags         A hash of tag to its pages, sorted by date
site.data         The contents of the files in _data
site.category_pages, site.tag_pages   URLs of generated list pages
site.source       The resolved source directory
site.output       The resolved output directory
site.layout       The resolved layout directory
site.urlpattern   Default URL pattern (/:category/:year/:month/:slug/)
site.extension    Default output extension (.html)
site.ignore       Patterns of top-level files not copied to the output
page.*

Everything defined in the page's front matter, plus:

page.content      The rendered body of the page
page.excerpt      The first paragraph of a markdown page
page.url          The URL of the page, relative to the site root
page.slug         The title, slugified (or the file name if no title)
page.id           A number unique to the page within a build
page.date         The page date (front matter, or the file's mtime)
page.year, page.month, page.day,
page.hour, page.minute, page.second   Parts of page.date, zero padded
page.filename     The output file the page is written to
page.dirname      The directory of page.filename
page.source_file_extension   The source file's extension (e.g. .md)
page.seo          Tags for <head>: description, canonical, Open Graph, JSON-LD
page.markdown_url The URL of the page's Markdown copy, if it has one
page.posts        On a generated category or tag page: its pages
paginator         On a paginated page; see App::Dapper::Collections

URLs and output files

Pages with categories or their own urlpattern are written to the path their URL describes. The pattern may use :category, :year, :month, :day, :hour, :minute, :second and :slug. A URL ending in / is written as index plus the page extension inside that directory. Other pages keep the path of their source file, with the page extension.

Generated files

After the pages, Dapper writes a sitemap, a feed (if feed is set), Markdown copies of pages and llms.txt (see App::Dapper::Publish), can generate category and tag pages and paginate lists (see App::Dapper::Collections), and can build a search index with Pagefind. Files that an earlier build wrote and this one did not are removed.

Options

Dapper provides a number of optional command line switches:

-s, --source=source directory

Specify the directory containing source files to process. If this command line option is not present, it defaults to the source setting in the config file, or "_source".

-o, --output=output directory

Specify the directory to place the output files in. If this command line option is not present, it defaults to the output setting in the config file, or "_output".

-l, --layout=layout directory

Specify the directory containing layout files. If this command line option is not present, it defaults to the layout setting in the config file, or "_layout".

-c, --config=config file

Specify the config file name to use. If this command line option is not present, it defaults to "_config.yml".

-p, --port=port

Specify the port to use for the serve command. Defaults to 8000.

-q, --quiet

Only print errors.

-C, --directory=directory

Run in this directory instead of the current one.

-t, --template=name

For the init command: the starter project to create, default or blog.

--json

For the check command: print the report as JSON.

-h, --help

Get help on available commands and options.

-v, --version

Print the version and exit.

METHODS

Dapper may be used directly from a script as well. The following methods are available:

new

Create a new Dapper object. Example:

my $d = App::Dapper->new();

Alternatively, the source dir, output dir, layout dir, and configuration file may be specified. Any of them may be undef, in which case the value from the configuration file (or the default) is used. Example:

my $d = App::Dapper->new("_source", "_output", "_layout", "_config.yml");

After creating a Dapper object, the following hash elements may be accessed:

use App::Dapper;

my $d = App::Dapper->new();

print "Source directory: $d->{source}\n";
print "Output directory: $d->{output}\n";
print "Layout directory: $d->{layout}\n";
print "Config file: $d->{config}\n";
print "Object instantiation time: $d->{site}->{time}\n";

The directories are updated from the configuration file when the site is built or served. Set $d->{quiet} to a true value to suppress progress messages.

init

Initializes a new skeleton project in the current directory of the calling script, using the source dir, layout dir and config file given to "new". Nothing is written if any of the files already exist. Example usage:

use App::Dapper;

my $d = App::Dapper->new();
$d->init();

Set $d->{template} to blog first for a complete starter blog (see App::Dapper::Init).

build

Build the site. Example:

use App::Dapper;

my $d = App::Dapper->new();
$d->build();

When the site is built, it is done in three steps:

1. Parse. In this step, the configuration file is read. In addition, all the source files in the source directory as well as the layout files in the layout directory are read and stored in the site hash.

2. Transform. Combine source and layout files.

3. Render. Save output files to the output directory.

A Dapper object may be built any number of times; each build starts fresh.

check

Build the site into a temporary directory and return a report of every problem found, without touching the output directory. See App::Dapper::Check.

my $report = $d->check();
print "ok\n" if $report->{ok};

agents

Write or update AGENTS.md (and a CLAUDE.md if there isn't one), which explains the project to AI coding agents. See App::Dapper::Agents.

deploy

Build, check and publish the site to a target set under deploy in _config.yml (Amazon S3, GitHub Pages, or a command). Takes the target name (optional if there is only one) and options: dry_run, force, no_build. See App::Dapper::Deploy.

$d->deploy('s3', dry_run => 1);

import_from

Import the pages of another site into the source directory. Takes the kind of site (wordpress, jekyll, hugo or medium), the file or directory to import, and options: to (the directory for posts, default blog) and dry_run. See App::Dapper::Import.

$d->import_from('wordpress', 'export.xml');

mcp

Run a Model Context Protocol server on standard input and output, so that AI assistants can read, write, build and check the site. See App::Dapper::MCP.

serve

Serve the site locally. Pass in the port number. The port number will be used to serve the site contents from the output directory like this: http://localhost:<port>. Here is an example, using the default port 8000:

use App::Dapper;

my $d = App::Dapper->new();
$d->serve("8000");

The following is equivalent:

$d->serve();

This method only serves what is already in the output directory (as read from the project file, if there is one); it does not build the site. The dapper serve command builds and watches the site in a separate process while it serves.

watch

Build the site, then rebuild it whenever a file in the project changes, is added, or is removed. The output directory and dot files are not watched. Errors in a rebuild are reported without stopping the watch. Pass the polling interval in seconds (default: 1).

$d->watch();

snapshot

Returns a hash reference of every watched file in the project mapped to its modification time and size. Used by "watch" to detect changes.

expand_urlpattern

Takes a URL pattern (e.g. /:category/:year/:month/:slug/) and a hash of page values, and returns the URL with each :name token replaced. The tokens are :category, :tag, :year, :month, :day, :hour, :minute, :second and :slug. Tokens with no value are removed along with their slash.

AUTHOR

Mark Benson, <mark at jayber.org>

BUGS

Please report any bugs or feature requests at https://github.com/markdbenson/dapper/issues.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc App::Dapper

You can also look for information at:

LICENSE AND COPYRIGHT

The MIT License (MIT)

Copyright (c) 2002-2026 Mark Benson

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.