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 SiteIf 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 : _outputDirectories 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
sitenamespace. For instance,namein 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
indexlayout indicates that_layout/index.htmlshould be used. - 4. The
titleconfiguration 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: truein_config.ymlrestores the behavior of Dapper before 1.0, where all content and_config.ymlvalues were templates too.A
_schema.ymlfile in a source directory describes the front matter its pages must have; see App::Dapper::Schema. YAML and JSON files in_dataare available assite.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 initcommand, 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.ymlfile 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
sourcesetting 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
outputsetting 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
layoutsetting 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,
defaultorblog. - --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:
GitHub: source code and issue tracker
MetaCPAN
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.