# Dapper
[](https://github.com/markdbenson/dapper/actions/workflows/test.yml)
[](https://metacpan.org/dist/App-Dapper)
A publishing tool for static websites
Dapper is a command-line application called `dapper` which you can use
to create static websites. Install it whichever way suits you:
$ brew install markdbenson/tap/dapper # Homebrew, on macOS or Linux
$ cpanm App::Dapper # CPAN, if you use Perl
or run it with [Docker](#install), with nothing else installed. Then:
$ dapper init # Initialize current directory with new site
$ dapper serve # Build and serve locally at http://localhost:8000
Dapper has three goals:
1. **Simple**. Learning Dapper is easy -- it gets out of the way so you can
write content, develop layouts, and deploy to production the way you
want.
2. **Flexible**. Content is written in
[Markdown](https://metacpan.org/pod/Text::MultiMarkdown), and
templates are written using the TT3 mini-language from
[Template::Alloy](https://metacpan.org/pod/Template::Alloy) for
maximum flexibility.
3. **Pragmatic**. The easy things are easy and the hard things are
possible. Dapper was created to solve problems in a straight-forward
and intuitive way.
Why static? Decent question. Here are some reasons:
1. **Fast**. Static pages are fast to load and easy to cache. Content
management systems, on the other hand, may contact the database at
least one time per page request, process the results, merge with a
templating system, and serve the result to the user's web browser.
2. **Cheap**. Having a static website means that options for hosting those
static files also just got a lot more simple. No database is needed and
no real processing power for scripting is needed. For example, with a
static website, it becomes possible to host the site on
[Github Pages](https://pages.github.com/) for free, or
[Amazon S3](http://aws.amazon.com/s3/) for very modest fees.
3. **Secure**. It's much more secure to host a static website than a
dynamic one. Content management systems that use scripting languages
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**
* Content in Markdown (with highlightable fenced code blocks) or HTML, with YAML front matter.
* Layouts in the TT3 mini-language from Template::Alloy. Content is safe by default: it is never run as template code unless a page asks.
* Front matter schemas, data files, categories, tags, pagination, and generated category and tag pages.
* A built-in sitemap, Atom feed, SEO and structured data tags, and Markdown copies of pages with an `llms.txt` index for AI tools.
* Components for callouts, videos, galleries, buttons, figures and maps in Markdown, without template code.
* Image sizes, responsive copies, WebP and lazy loading, with one setting.
* Drafts, and posts scheduled for a future date.
* `dapper check` finds broken links, front matter mistakes, and accessibility and SEO problems; `dapper serve` rebuilds and reloads the browser as you edit.
* `dapper import` brings in a WordPress, Jekyll, Hugo or Medium site.
* An MCP server, so AI assistants can write, check and build the site, with your schemas as guardrails.
* Starter themes for a blog, a portfolio, a small business and documentation, or any theme from a folder or git repository.
* `AGENTS.md` in every project, so AI coding agents know its conventions from the start.
* `dapper deploy` publishes to Amazon S3, GitHub Pages or anywhere, after checking the site.
* Install from CPAN, as a single file, with Homebrew, or with Docker.
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)
* [Templates and themes](#templates-and-themes)
* [Importing a site](#importing-a-site)
* [Tutorial: Build a Blog](#tutorial-build-a-blog)
* [Configuration](#configuration)
* [Source](#source)
* [Template code in content](#template-code-in-content)
* [Front matter schemas](#front-matter-schemas)
* [Data files](#data-files)
* [Source file types](#source-file-types)
* [Assets](#assets)
* [Drafts and scheduled posts](#drafts-and-scheduled-posts)
* [Clean builds](#clean-builds)
* [Headings](#headings)
* [Text](#text)
* [Lists](#lists)
* [Tables](#tables)
* [Images](#images)
* [Image sizes and responsive images](#image-sizes-and-responsive-images)
* [Footnotes](#footnotes)
* [Components](#components)
* [Layout](#layout)
* [Variables](#variables)
* [Pagination](#pagination)
* [Category and tag pages](#category-and-tag-pages)
* [Comments](#comments)
* [Filters](#filters)
* [Conditionals](#conditionals)
* [Iteration](#iteration)
* [Blocks](#blocks)
* [Perl code](#perl-code)
* [Includes](#includes)
* [Macros](#macros)
* [Plugins](#plugins)
* [Chomping](#chomping)
* [Dumping](#dumping)
* [Publishing for Search Engines and AI](#publishing-for-search-engines-and-ai)
* [Sitemap](#sitemap)
* [Feed](#feed)
* [Redirects](#redirects)
* [SEO tags](#seo-tags)
* [Markdown copies and llms.txt](#markdown-copies-and-llmstxt)
* [Search](#search)
* [AI Assistants (MCP)](#ai-assistants-mcp)
* [AGENTS.md](#agentsmd)
* [The MCP server](#the-mcp-server)
* [Deployment](#deployment)
* [Deploying with dapper deploy](#deploying-with-dapper-deploy)
* [Amazon S3](#amazon-s3)
* [GitHub Pages](#github-pages)
* [What Dapper Doesn't Do](#what-dapper-doesnt-do)
* [Upgrading from 1.0](#upgrading-from-10)
* [Upgrading to 1.0](#upgrading-to-10)
* [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
Other ways to install, if you'd rather not use `cpanm`:
* **A single file.** Download `dapper` from the
[latest release](https://github.com/markdbenson/dapper/releases/latest).
It runs with any Perl 5.10 or newer and needs nothing else installed:
$ curl -fsSLo dapper https://github.com/markdbenson/dapper/releases/latest/download/dapper
$ chmod +x dapper
$ sudo mv dapper /usr/local/bin/
* **Homebrew:** `brew install markdbenson/tap/dapper`
* **Docker**, with no Perl at all. Run it in your project directory:
$ docker run --rm -v "$PWD":/site ghcr.io/markdbenson/dapper build
$ docker run --rm -v "$PWD":/site -p 8000:8000 ghcr.io/markdbenson/dapper serve
The image includes git, so themes from a git URL and `dapper deploy` to
GitHub Pages work (mount your SSH keys, or use an HTTPS URL with a token).
It doesn't include the AWS CLI, so deploy to Amazon S3 from your own
machine.
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
To start from a complete site instead, pick a template:
$ dapper templates
blog A blog: paginated home page, posts, category and tag pages, feed, a schema for posts
business A small business: services, opening hours, contact details and news, from one data file
default The smallest project: a project file, one layout and one page
docs Documentation: a sidebar from a data file, previous and next links, code highlighting and search
portfolio A portfolio: a grid of projects with images, and about and contact pages
$ dapper init --template business
See [Templates and themes](#templates-and-themes).
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
...
M/MD/MDB/App-Dapper-0.22.tar.gz
/Library/Perl/5.34/App/Dapper.pm
Installed: 0.21
CPAN: 0.22 Not up to date
Mark Benson (MDB)
In this example, you can see there is a newer version available. Upgrade
like this:
$ cpan App::Dapper
Stable releases are available on CPAN, but development happens at
[Github](https://github.com/markdbenson/dapper). If you like living on the
edge, install from the latest development tip like this:
$ cpanm https://github.com/markdbenson/dapper.git
A list of recent commits can also be
[viewed on Github](https://github.com/markdbenson/dapper/commits/master).
### Downgrade
If you want to install an older version of Dapper, first find the link on
[backpan](http://backpan.perl.org/authors/id/M/MD/MDB/). Then, install like
this (e.g. v0.13):
$ cpanm http://backpan.perl.org/authors/id/M/MD/MDB/App-Dapper-0.13.tar.gz
If you want, you can also install from source. To do that, you just need to
download and unpack the desired release from
[backpan](http://backpan.perl.org/authors/id/M/MD/MDB/), or clone the
repository from Github. Then, do this:
$ perl Makefile.PL
$ make
$ make test
$ make install
## Usage
When you install 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. The following sections show you how.
### Init
The `dapper init` command initializes a new site. Note that the
site will be initialized in the current directory. Therefore, it's usually
best to create a blank directory that can be used for this purpose. A
description of the resulting directory structure is available in the
[Directory Structure](#directory-structure) section.
# Initialize the current directory with a fresh skeleton of a site
$ dapper init
# ...or with a complete starter blog
$ dapper init --template blog
# ...or a portfolio, a small business site, or documentation
$ dapper init --template business
# ...or a theme from a folder or a git repository
$ dapper init --template https://github.com/someone/dapper-theme.git
# List the built-in templates
$ dapper templates
See [Templates and themes](#templates-and-themes) for what each one includes.
### Build
After the site has been initialized, build it using the `dapper build`
command. Dapper takes care of reading the source files, combining them
with the layout template(s), and saving the result in the `_output`
directory.
# Build the site
$ dapper build
### Watch
The `dapper watch` command builds the site and then watches all the files
in the project for changes. If any changes occur, the site is rebuilt
again. The `dapper watch` command will do this repeatedly until you exit
using *Ctrl-C*.
# Rebuild the site if anything changes
$ dapper watch
Specifically, the dapper command watches all files in the current
directory and all subdirectories, including the project file
(`_config.yml`), and notices files that are added or removed. It does not
watch:
* Files and directories that begin with a period (.), such as `.git`.
* The output directory (`_output`, or whatever `output` is set to) and
everything in it.
If a rebuild fails (for instance, because of a typo in a layout), the
error is printed and Dapper keeps watching.
### Serve
The `dapper serve` command builds the site, serves the contents of the
`_output` directory using Dapper's built-in webserver, and handles auto-
rebuilding your site if anything changes. You can think of the `dapper
serve` command as a combination of `build`, `watch`, and `serve`.
# Serve the site locally at http://localhost:8000
$ dapper serve
If you want to use a different port number (e.g. 9000), specify it using
the *-p* option:
# Serve the site locally at http://localhost:9000
$ dapper -p 9000 serve
`dapper serve` shows [drafts](#drafts-and-scheduled-posts) and pages dated
in the future, so you can see them before they're published. While it is
running, pages in your browser reload by themselves after each rebuild. The server listens on every network interface, so other
devices on your network can reach it too, which is handy for testing on a
phone.
### Check
The `dapper check` command builds the site into a temporary directory and
reports every problem it finds, without touching the output directory:
front matter that can't be read or doesn't match its
[schema](#front-matter-schemas), missing layouts, mistakes in templates, two
pages that would be written to the same file, links and images that lead
nowhere, and pages without a title.
$ dapper check
error: _source/blog/new.md: links to /contact.html, which is not in the site
warning: _source/about.md: the image team.jpg has no alt text; describe it, or use alt="" if it is decoration
Checked 12 pages: 1 error, 1 warning.
It also warns about problems for people using screen readers and for search
engines:
* **Accessibility:** images without alt text, headings that skip a level
(an `h2` followed by an `h4`), an `` tag without a `lang`
attribute, and links with no text or only "click here" or "here".
* **SEO:** pages with no description (from `description` in the front
matter, or the first paragraph), two pages with the same title or
description, titles over 70 characters and descriptions over 160.
Generated pages, pages with `sitemap: false`, `404.html` and the second
and later pages of a list are left out.
Turn either group off in `_config.yml`:
check:
accessibility: false
seo: false
A Markdown image needs its alt text in the brackets: ``.
`` is reported. For an image that is only decoration, write
`` instead.
`dapper check` checks the site as `dapper build` would build it, so drafts
and pages dated in the future are left out and listed at the end. Add
`--drafts` to check them too.
It exits with status 1 when there are errors, so it can stop a deploy
script or a CI job. Add `--json` for a report that scripts and AI
assistants can read:
$ dapper check --json
### Deploy
The `dapper deploy` command builds the site, checks it, and publishes it to
Amazon S3, GitHub Pages, or wherever a command of your own sends it. See
[Deploying with dapper deploy](#deploying-with-dapper-deploy).
$ dapper deploy --dry-run
$ dapper deploy
### Agents
The `dapper agents` command writes or updates `AGENTS.md`, which explains the
project to AI coding agents. See [AI Assistants (MCP)](#ai-assistants-mcp).
### Import
The `dapper import` command brings in the pages of a WordPress, Jekyll, Hugo
or Medium site. See [Importing a site](#importing-a-site).
$ dapper import wordpress export.xml
$ dapper import jekyll ../old-site --dry-run
### MCP
The `dapper mcp` command runs a server that AI assistants can use to work on
the site. See [AI Assistants (MCP)](#ai-assistants-mcp).
### Options
Every command accepts these options. Directories given on the command line
take precedence over the ones in `_config.yml`, which take precedence over
the defaults.
Option | Description
---------------------------|------------------------------------------------------
`-s`, `--source` *dir* | Source directory (default: `source` in `_config.yml`, or `_source`)
`-o`, `--output` *dir* | Output directory (default: `output` in `_config.yml`, or `_output`)
`-l`, `--layout` *dir* | Layout directory (default: `layout` in `_config.yml`, or `_layout`)
`-c`, `--config` *file* | Project file (default: `_config.yml`)
`-p`, `--port` *number* | Port for `dapper serve` (default: `8000`)
`-q`, `--quiet` | Only print errors
`-C`, `--directory` *dir* | Run in this directory instead of the current one
`-t`, `--template` *name* | For `init`: a built-in template (see `dapper templates`), a directory, or a git URL
`--json` | For `check`: print the report as JSON
`--drafts` | For `build`, `watch` and `check`: include drafts and pages dated in the future
`--to` *dir* | For `import`: the directory in `_source` that posts go in (default: `blog`)
`--dry-run` | For `deploy` and `import`: show what would happen without doing it
`--force` | For `deploy`: publish even if `dapper check` finds errors
`--no-build` | For `deploy`: publish the output directory as it is
`-h`, `--help` | Print usage
`-v`, `--version` | Print the version
### Help
To get more information about command-line options available, the current
version of Dapper that you have installed on your system, or further
documentation available, see the following:
# Get help on usage and switches
$ dapper -h
# Print the version
$ dapper -v
## Directory Structure
After running the [`dapper init`](#init) command, the following directory
structure will be created:
_config.yml
_layout/
index.html
_source/
index.md
Here is a description of each file:
**_config.yml**
The configuration file is a [YAML](http://www.yaml.org/) file that specifies
key configuration elements for your static website. The default
configuration file is as follows:
# Dapper configuration file
---
name : My Site
If you want to use a separate source, layout, or output directory, you may
specify it in this file. For instance:
# Dapper configuration file
---
name : My Site
source : _source
layout : _layout
output : _output
There are a few definitions that affect the way that Dapper behaves. Those
are defined in the [Configuration](#configuration) section. Those and any
others that you choose to specify become available in the layout templates
under the `site` namespace. For instance, `name` is available in templates
like this:
[% 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.
[% page.title %]
**_layout/index.html**
Layout files are processed using the TT3 mini-language from the Template::Alloy
template system. The initial layout file that is given after you run the `dapper
init` command, is this:
[% page.title %]
[% page.content %]
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 YAML
portion of text files can be referenced under the "page" namespace (e.g.
`[% page.title %]`).
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
Now, you'll see a new directory that has been created (`_output`) that
contains a single file (`index.html`) containing a mashup of the source
file and the layout template.
**_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:
Welcome
Hello world.
# Templates and themes
`dapper init --template ` starts a project from a template. The
built-in ones are complete, working sites you edit to make your own; each is
responsive, accessible (with a skip link, landmarks and visible focus), has
a dark mode, passes `dapper check`, and comes with a schema and notes in
`AGENTS.md` so an AI assistant knows how to fill it in.
Template | What you get
------------|----------------------------------------------------------------
`default` | The smallest project: a project file, one layout and one page
`blog` | A paginated home page, posts with tags, category and tag pages, a feed, a schema for posts, a menu from a data file, code highlighting and optional search
`portfolio` | An introduction and a grid of projects with images; a page per project with its details; about and contact pages. Projects must have an image with alt text.
`business` | Services, opening hours and contact details, all from one data file (`_data/business.yml`), shown on every page and published as structured data for search engines; a notice banner for holiday hours; a news section
`docs` | Pages with a sidebar from `_data/nav.yml`, previous and next links in the same order, code highlighting in light and dark, and optional search
A template can also be any directory or git repository laid out like a
project, which is how themes are shared:
$ dapper init --template ./my-theme
$ dapper init --template https://github.com/someone/dapper-theme.git
Dapper copies its files (but not `.git`, the output directory or `.dapper`).
If the theme has an `AGENTS.md`, it is kept, and Dapper adds its guide to
the project below it.
To make a theme, build a site the way you like it, add a `_schema.yml` for
each kind of page and notes for assistants in `AGENTS.md`, check it with
`dapper check`, and publish the directory as a git repository.
# Importing a site
`dapper import` brings the writing from a WordPress, Jekyll, Hugo or Medium
site into a Dapper project. Start a project with the starter you like, then
import into it:
$ dapper init --template blog
$ dapper import wordpress ~/Downloads/export.xml
Imported 48 posts and 5 pages into _source (3 as drafts).
Check: images that still load from the old WordPress site (wp-content/uploads); copy them into the site (12 pages, such as _source/blog/hello-world.html)
Run "dapper check" to find links that need fixing.
Add `--dry-run` to see what would happen first, and `--to posts` to put
posts in `_source/posts` instead of `_source/blog`. Nothing already in the
source directory is overwritten, so it's safe to run again.
Source | Give it | What comes in
-------|---------|--------------
`wordpress` | The export file from Tools, Export | Posts (into `blog`) and pages, as HTML, with their title, date, categories, tags and excerpt. Drafts, pending and private posts become drafts. `[caption]` becomes a figure, and `[embed]` or a YouTube or Vimeo address on its own line becomes a video.
`jekyll` | The site's folder | Posts from `_posts`, drafts from `_drafts`, and every other page. `highlight` blocks, `site.baseurl`, `relative_url` and `post_url` are converted. Folders like `assets` and `images` are copied.
`hugo` | The site's folder | Every page in `content`, with YAML, TOML or JSON front matter. Page bundles bring their files, `static` is copied, `aliases` become [redirects](#redirects), and the `youtube`, `vimeo` and `figure` shortcodes become [components](#components).
`medium` | The export zip from Medium's settings, or its folder | Each story, as HTML without Medium's markup. Unpublished stories become drafts.
Pages keep their old addresses where they had their own (WordPress, Jekyll
and Hugo), using `urlpattern`, so links from elsewhere keep working. Posts
get the project's `post` layout if it has one.
Imported pages are made to fit the `_schema.yml` of the folder they land
in, so the site still builds. In the blog starter, posts must be in the
`blog` category, so each post gets it, and WordPress categories become
tags instead. A missing title becomes "Untitled", and text longer than the
schema allows is shortened. The import lists each kind of change it made.
When it's done, `dapper import` lists what it couldn't convert, such as
WordPress shortcodes, Liquid tags or Hugo shortcodes it doesn't know, and
images that still load from the old site. Look at those pages, then run
`dapper serve` to see the result and `dapper check` to find links that need
fixing.
# Tutorial: Build a Blog
This walkthrough builds a small blog: a home page that lists the latest
posts, one page per post, a stylesheet, and the feed, sitemap and SEO tags
that Dapper generates for you. Every file is shown in full, so you can copy
them as they are.
(`dapper init --template blog` creates a project much like this one, with
category and tag pages, a schema for posts and a menu as well. This
tutorial builds it by hand so you can see how the pieces fit.)
When it's done, the project looks like this:
_config.yml
_layout/
index.html The page wrapper used by every page
post.html A post, wrapped in index.html
_source/
index.html The home page: a list of posts
blog/
hello-world.md
second-post.md
css/
site.css Copied to the output as it is
**1. The project file.** `url` is the address the site will be published at
(leave off the trailing slash); the sitemap, the feed and the SEO tags use
it to make absolute links. `timezone` is the time zone your post dates are
written in. `feed` turns on an Atom feed of the blog.
# Dapper configuration file
---
name: My Blog
description: Notes on building things.
url: https://example.com
author: Jane Doe
timezone: America/Chicago
feed:
category: blog
**2. The main layout**, `_layout/index.html`. Pages without a `layout`
setting use this one. `[% page.seo %]` adds the page's description,
canonical link, feed link, Open Graph tags and structured data.
```html
[% page.title | html %] - [% site.name | html %]
[% page.seo %]
[% site.name | html %]
[% page.content %]
```
**3. A post layout**, `_layout/post.html`. Its front matter says to wrap
it in the `index` layout, so a post gets the header and footer too.
```html
---
layout: index
---
[% page.title | html %]
[% page.date.strftime('%d %B %Y') %]
[% page.content %]
```
**4. Posts**, in `_source/blog/`. The `categories: blog` setting puts each
post in `site.categories.blog` (and so in the feed), and also means the
post is written to the path described by `urlpattern`
(`/:category/:year/:month/:slug/` by default), so this one becomes
`/blog/2026/10/hello-world/`.
```
---
title: Hello World
layout: post
categories: blog
date: 2026-10-01T09:00:00
---
This is my first post. This paragraph becomes the excerpt.
The rest of the post goes here.
```
Add a second post, `_source/blog/second-post.md`, the same way with a
later date.
**5. The home page**, `_source/index.html`. It is an `.html` file rather
than `.md` so that Markdown doesn't touch its HTML, and it sets
`template: true` because its content uses template code (see [Template
code in content](#template-code-in-content)). `paginate` hands it the posts
in `paginator.items`, newest first, ten to a page.
```html
---
title: Home
template: true
paginate:
category: blog
per_page: 10
---
[% END %]
[% IF paginator.next_url %]Older posts[% END %]
```
**6. A stylesheet**, `css/site.css`. Directories at the top of the project
are copied to the output as they are (see [Assets](#assets)), so this is
served at `/css/site.css`.
body { font-family: sans-serif; max-width: 40em; margin: auto; }
**7. Build and look.**
$ dapper serve
Browse to http://localhost:8000. Edit any file while `dapper serve` is
running and the site is rebuilt, and the page in your browser reloads by
itself. The output directory now contains:
_output/
index.html
blog/2026/10/hello-world/index.html
blog/2026/10/hello-world/index.md A Markdown copy, for AI tools
blog/2026/10/second-post/index.html
blog/2026/10/second-post/index.md
css/site.css
feed.xml The Atom feed
sitemap.xml For search engines
llms.txt An index for AI tools
llms-full.txt
**8. Check it.**
$ dapper check
Checked 3 pages: 0 errors, 0 warnings.
`dapper check` finds broken links, missing layouts and front matter
mistakes, without touching the output directory.
From here, you might add [category and tag pages](#category-and-tag-pages),
a [schema](#front-matter-schemas) so every post has what it needs,
[search](#search), or let an [AI assistant](#ai-assistants-mcp) write and
publish posts for you.
# Configuration
Dapper allows you to create static websites in just about any way that you
want to. The project configuration file (`_config.yml`) allows you to
specify special instructions to Dapper and also to guide the process of
rendering the site using the source files (`_source/`) and the layout
templates (`_layout/`).
Variables specified in `_config.yml` are done using YAML. Here is the
default configuration file created after a `dapper init` command:
# Dapper configuration file
---
name : My Site
Note that lines beginning with `#` are comments. Lines with `---` mark the
beginning/end of a YAML "document". What follows are `:`
pairs or arrays, arranged hierarchically:
# Dapper config file
---
name: My Portfolio
url: https://example.com/
source : _source
output : _output
layout : _layout
links :
About : /about/
Blog : /blog/
GitHub : https://github.com/markdbenson
ignore :
- ^\.
- ^_
- ^design$
- ^README.md$
- ^Makefile$
A few settings change the way Dapper behaves:
Setting | Default | Meaning
--------------|-------------------------------------|---------------------------------------------
`source` | `_source` | Directory of source files
`output` | `_output` | Directory the site is written to
`layout` | `_layout` | Directory of layout templates
`urlpattern` | `/:category/:year/:month/:slug/` | URL (and output path) of pages with categories; see [Source](#source)
`extension` | `.html` | Extension of output files
`ignore` | `^\.`, `^_`, `^dapper$` | Regular expressions for top-level files that are not copied to the output
`timezone` | your computer's time zone | Time zone of dates written without one, e.g. `America/Chicago`. A page may set its own `timezone`.
`url` | (none) | The address the site is published at, e.g. `https://example.com`. Needed for the sitemap and feed, and for absolute links in `llms.txt` and `page.seo`.
`description` | (none) | A sentence about the site, used by `llms.txt`, the feed and `page.seo`
`author` | (none) | Used by the feed and `page.seo`
`image` | (none) | The default image for `page.seo` (Open Graph)
`data_dir` | `_data` | Directory of [data files](#data-files)
`templates_in_content` | `false` | Run template code in all content and in `_config.yml` values, as Dapper did before 1.0; see [Template code in content](#template-code-in-content)
`markdown_twins` | `true` | Write a Markdown copy next to each page made from Markdown
`llms_txt` | `true` | Write `/llms.txt` and `/llms-full.txt`
`sitemap` | `true` | Write `/sitemap.xml` (when `url` is set)
`feed` | (off) | `true`, or settings: `category`, `path` (default `/feed.xml`), `limit` (default 20), `title`
`category_pages`, `tag_pages` | (off) | Generate a page per category or tag; see [Category and tag pages](#category-and-tag-pages)
`search` | `false` | Build a search index with Pagefind; see [Search](#search)
`search_command` | `pagefind` | The command to run for search, e.g. `npx -y pagefind`
`clean` | `true` | Remove files that an earlier build wrote and this one did not
`redirects` | (none) | Old URLs and the new URLs they redirect to; see [Redirects](#redirects)
`deploy` | (none) | Where `dapper deploy` publishes; see [Deploying with dapper deploy](#deploying-with-dapper-deploy)
Directories given on the command line (`-s`, `-o`, `-l`) take precedence
over these settings.
Any variable specified in `_config.yml` can be used in a template. In the
example above, name can be used like this:
[% site.name %]
URL can be used like this:
[% site.name %]
The links (key/value pairs) can be listed like this:
[% for link in site.links %]
[% link.key %]
[% end %]
All of the items in the `ignore` array can be shown like this:
[% for i in site.ignore %]
[% i %]
[% end %]
See the official [YAML](http://yaml.org/) specification, or the
[YAML::PP](https://metacpan.org/pod/YAML::PP) Perl module
documentation (Dapper's YAML parsing engine) for more information.
# Source
Source files in Dapper are written in
[Markdown](https://daringfireball.net/projects/markdown/). Markdown is a
markup language that allows you to write content in a natural way, and
have that text converted to XHTML for displaying on the web.
Writing with Markdown allows you to separate the content and structure of
your document from the formatting which allows you to focus on the actual
writing.
Source files that are pages start with [YAML](http://yaml.org/) "front
matter". The front matter is denoted by leading and trailing lines that
each contain a sequence of three dashes, and must begin on the very first
line of the file. Example:
```
---
layout: post
title: Post Title
---
Here is the text of the post.
```
The variables specified as YAML are available under the `page` namespace
in layouts. The body of the page (`Here is the text of
the post.`) in the above example, is available as `content` in Template
Toolkit templates.
Files in the source directory that do *not* start with front matter, such
as images, PDFs, zip files or plain text, are copied to the same place in
the output directory exactly as they are.
Variable definitions in source files that carry special meaning are as
follows:
* `extension: .html` is the default used if not specified. To override,
specify a new value for `extension` for that particular page. `extension`
may also be specified in the `_config.yml` file to apply it globally.
* `urlpattern: /:category/:year/:month/:slug/` defines the URL path for
the file. This may also be specified in `_config.yml` as well. If not
specified, the following is used: `/:category/:year/:month/:slug/`. A
full list of pattern options are as follows:
- `:category` - The category of the page as defined by the page's
YAML.
- `:year` - The year the page was published as defined either by the
`date` field in the page's YAML part, or from the file modification
timestamp.
- `:month` - The month the page was published as defined either by
the
`date` field in the page's YAML part, or from the file modification
timestamp.
- `:day` - The day the page was published as defined either by the
`date` field in the page's YAML part, or from the file modification
timestamp.
- `:hour` - The hour the page was published as defined either by the
`date` field in the page's YAML part, or from the file modification
timestamp.
- `:minute` - The minute the page was published as defined either by
the `date` field in the page's YAML part, or from the file
modification timestamp.
- `:second` - The second the page was published as defined either by
the `date` field in the page's YAML part, or from the file
modification timestamp.
- `:slug` - The title of the page with all non-ASCII characters
removed, all non-word characters removed, all spaces converted to
hyphens (`-`), and converted to lowercase. If the page has no
title, the source file name is used.
Tokens without a value (for instance `:category` on a page with no
categories) are removed along with their slash.
**Where the page is written.** Pages that have `categories`, or their
own `urlpattern` in their front matter, are written to the path their
URL describes. A URL that ends in `/` is written as `index.html` (or
`index` plus the page's `extension`) inside that directory. For
example, `_source/posts/0001.md` with:
---
title: Foo Bar Baz
date: 2015-08-01T10:00:00
urlpattern: /:year/:month/:slug.html
---
is written to `_output/2015/08/foo-bar-baz.html`, and `page.url` is
`/2015/08/foo-bar-baz.html`. All other pages keep the path of their
source file (`_source/about/index.md` becomes `_output/about/index.html`
with a `page.url` of `/about/`).
* `categories: blog` puts the page in `site.categories.blog`. A list
(`categories: [news, blog]`) puts it in each; the first is used for
`:category`.
* `date: 2014-05-02T10:30:00` sets the page's date. ISO 8601 date-times
(optionally with a time zone, e.g. `2014-05-02T10:30:00-05:00`), the
older `2014-05-02 10:30:00` format and plain dates (`2014-05-02`) are
accepted. Without a `date`, the file's modification time is used.
* `layout: post` selects `_layout/post.html`. Without a `layout`,
`_layout/index.html` is used.
* `template: true` runs the page's content as template code; see
[Template code in content](#template-code-in-content).
* `tags: [perl, writing]` puts the page in `site.tags.perl` and
`site.tags.writing`.
* `description`, `image` and `author` are used by `page.seo`, the feed
and `llms.txt`. Without a `description`, the excerpt is used.
* `updated: 2014-06-01` is when the page last changed, for the sitemap,
the feed and `page.seo`.
* `paginate` lists posts across several pages; see
[Pagination](#pagination).
* `markdown_twin: false`, `llms: false` and `sitemap: false` leave the
page out of the Markdown copies, `llms.txt` and the sitemap.
Here is an example that shows a few different types of YAML definitions
at the beginning of a source file and how to use those definitions in
templates.
```
---
name: My Site
menu:
Home: /
Portfolio: /portfolio/
About: /about/
Github: http://github.com/markdbenson
fruits:
- Apple
- Orange
- Banana
---
```
Front matter values are always available to layouts as `page.*`. To use
template directives in a page's own content, as in the example above, the
page needs `template: true` (see [Template code in
content](#template-code-in-content)). Only do that for content you trust,
especially with `EVAL_PERL` enabled (see [Perl code](#perl-code)). More information is available in [Appendix C:
Internals](#appendix-c-internals).
Dapper depends on
[MultiMarkdown](http://fletcherpenney.net/multimarkdown/). Or, more
specifically, the Perl module implementation of MultiMarkdown ([Text::
MultiMarkdown](https://metacpan.org/pod/Text::MultiMarkdown).
MultiMarkdown is based on the traditional definition of Markdown by
John Gruber of [Daring Fireball](http://daringfireball.net), but adds
additional nice features such as tables and footnotes.
The following sections describe the markup that Dapper accepts, including
headings, text, lists, footnotes, tables, and images. There are more
features of the MultiMarkdown engine that Dapper uses. See the
[MultiMarkdown documentation](http://fletcher.github.io/MultiMarkdown-4/)
on CPAN for details.
## Template code in content
Layouts are always processed as templates. A page's own content is not:
`[% ... %]` in a page is shown as it is, so you can write about template
code, or publish text from anywhere, without it running.
A page whose content should be processed as a template (a list of posts,
say) opts in with `template: true`:
---
title: Home
template: true
---
[% FOR post IN site.categories.blog.reverse %]
[% post.title | html %]
[% END %]
`templates_in_content: true` in `_config.yml` makes every page's content,
and every value in `_config.yml`, a template, as they were before Dapper
1.0. Use it for sites written for older versions; see [Upgrading to
1.0](#upgrading-to-10).
## Front matter schemas
A `_schema.yml` file in a source directory describes the front matter that
the pages in that directory (and in the directories below it, unless they
have a schema of their own) must have. For example,
`_source/blog/_schema.yml`:
required: [title, date, categories]
fields:
title:
type: string
max_length: 100
date:
type: date
categories:
type: list
values: [blog, notes]
tags:
type: list
draft:
type: boolean
rating:
type: integer
min: 1
max: 5
`required` lists the fields every page must set. Each entry in `fields`
can have:
Rule | Meaning
---------------------------|---------------------------------------------------
`type` | `string`, `number`, `integer`, `boolean`, `date`, `list`, `map` or `any`
`values` | The allowed values (for a `list`, the allowed items)
`pattern` | A regular expression a string must match
`min_length`, `max_length` | Limits on the length of a string
`min`, `max` | Limits on a number
Fields not listed in `fields` are allowed, unless the schema says
`additional: false`.
A build stops if any page doesn't match, listing every problem on every
page at once:
error: 2 problems with front matter (see the _schema.yml files):
_source/blog/new.md: "date" is required
_source/blog/new.md: "categories" has "news", which is not one of: blog, notes
`dapper check` reports the same problems, and the [MCP
server](#ai-assistants-mcp) refuses to write a page that doesn't match.
## Data files
YAML (`.yml`, `.yaml`) and JSON (`.json`) files in the `_data` directory are
available in templates as `site.data`, named after the file:
`_data/authors.yml` is `site.data.authors`, and `_data/menus/main.yml` is
`site.data.menus.main`. For example, with `_data/menu.yml`:
- label: Home
url: /
- label: About
url: /about.html
a layout can build the menu:
[% FOR item IN site.data.menu %]
[% item.label | html %]
[% END %]
The data directory is never copied to the output. Set `data_dir` in
`_config.yml` to use another directory.
## Source file types
What happens to a file in the source directory depends on whether it starts
with front matter and on its extension:
* **`.md` files with front matter** are pages. The body is converted from
Markdown to HTML, then combined with the layout.
* **Other files with front matter** (`.html`, `.xml`, `.txt`, ...) are
pages too, but the body is used as it is, without Markdown. Use these for
pages that are mostly HTML or template directives, such as a list of
posts, or for non-HTML output such as a feed. Set `extension` in the
front matter (e.g. `extension: .xml`) to choose the output file name's
extension; otherwise it is `.html`.
* **Files without front matter** are copied to the same place in the output
directory, untouched.
A page that uses template directives in its content needs `template: true`
(see [Template code in content](#template-code-in-content)). Markdown runs
before the directives are processed, so directives in a `.md` file are fine
inline, but a block of HTML and directives (a loop that builds a list of
links, say) is best kept in an `.html` source file, where Markdown can't
rewrap it in `
` tags.
Every file and directory in the source directory is processed except those
whose names start with a period. Directories starting with an underscore
are *not* skipped inside the source directory.
## Assets
Stylesheets, scripts, images and other files can live in either of two
places:
* **In the project directory**, next to `_source` (e.g. `css/`, `js/`,
`images/`). Every top-level file and directory is copied to the output as
it is, except those matching the `ignore` patterns in `_config.yml` (by
default: names starting with `.` or `_`). Add patterns for anything you
don't want published, like `README.md`, `Makefile` or a `design`
directory.
* **In the source directory**, alongside the pages. Files there without
front matter are copied as they are, which keeps an article's images next
to its text.
Link to assets with absolute paths (`/css/site.css`) so the links work from
pages at any depth.
## Drafts and scheduled posts
A page with `draft: true` in its front matter is a draft. `dapper build`
and `dapper deploy` leave it out, along with any page whose `date` is in the
future. They are left out completely: they aren't in `site.pages`, the
categories and tags, the feed, the sitemap or `llms.txt`.
---
title: Coming soon
draft: true
---
`dapper serve` shows drafts and pages dated in the future, so you can see
them as you write. `dapper build --drafts` and `dapper check --drafts`
include them too. `dapper deploy` never does.
To publish a draft, remove `draft: true` (or set it to `false`). A page
dated in the future is published by the first build after its date, so to
publish posts on schedule, build and deploy the site regularly, for
example every morning from a scheduled CI job. Set `future: true` in
`_config.yml` to publish pages dated in the future straight away.
`dapper check` lists the pages it left out:
$ dapper check
Not published: 1 draft, 2 scheduled (use --drafts to include them).
Checked 12 pages: 0 errors, 0 warnings.
A link to a draft from a published page is reported as a broken link, since
the draft isn't on the site yet.
## Clean builds
When you rename or remove a source file, the next build removes the file it
used to produce. Dapper keeps a list of the files it writes (in
`.dapper/manifest.json` in the project directory) and only ever removes
files on that list, so anything you put in the output directory yourself,
such as a `.git` directory or a `CNAME` file, is left alone. Add `.dapper/`
to your `.gitignore`. Set `clean: false` in `_config.yml` to turn this off.
## Headings
Headings are specified by prefixing with pound signs (`#`):
```
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
```
Alternatively, headings may be specified using an underline style:
```
Alternative H1
==============
Alternative H2
--------------
```
## Text
Text elements may be formatted as well. Here are some examples of bold,
italics, code, links, and blockquotes:
Markdown | Result
----------------------------------------|----------------------------------
This is a normal paragraph. | This is a normal paragraph.
This text is `**bold**.` | This text is **bold**.
This text is also `__bold__.` | This text is also **bold**.
This text is `*italicized*.` | This text is *italicized*.
This text is also `_italicized_.` | This text is also _italicized_.
`` `This is some code.` `` | `This is some code.`
Link to `[Example](https://example.com).` | Link to [Example](https://example.com/).
Link to `[Example][ln1].` | Link to [Example][ln1].
Link to `.` | Link to https://example.com.
`> This is the first level of quoting.` | The first level of quoting.
`>> This is a nested blockquote.` | A nested blockquote.
`[ln1]: https://example.com "Example"`
[ln1]: https://example.com "Example"
Code is placed in `backticks` (see [above](#text)), or as a "fenced code block"
by surrounding an entire block of text with three backticks in a row.
Put the language after the opening backticks, and the block is marked with
a `language-*` class (here, `
`), which
client-side highlighters such as [highlight.js](https://highlightjs.org/)
and [Prism](https://prismjs.com/) use to color it. The blog template
(`dapper init --template blog`) sets up highlight.js.
```perl
#!/usr/bin/perl -w
print "Hello, world!\n";
```
## Lists
Lists may be specified by prefixing lines with an asterisk (`*`), minus
(`-`), or plus (`+`). Hierarchical representations are accomplished
via indentation.
```
* Milk
* Bread
* Cheese
- Cheddar
+ Mild
+ Medium
+ Sharp
- Limburger
* Rice
```
Numbered lists are prefixed by numbers. The order of the numbers doesn't
matter -- just that they are numbers. Example:
```
1. One
2. Two
3. Three
1. Three.One
2. Three.Two
4. Four
```
A definition list is a line followed by a line that starts with a colon
and a list of definitions. Examples:
```
Apple
: * Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
* Also the makers of really great products.
Banana
: 1. A delicious fruit that can be hazardous if left on the ground.
2. A fruit that comes with it's own packaging
Orange
: - The fruit of an evergreen tree of the genus Citrus.
```
## Tables
Here is an example table that has a header row and a reference. The first
column is left-justified, the middle column is centered, and the third
column is right justified:
```
| First Header | Second Header | Third Header |
| :----------- | :-----------: | -------------------: |
| First row | Data | Very long data entry |
| Second row | **Cell** | *Cell* |
[simple_table]
```
More information is available in the [MultiMarkdown
documentation](http://fletcher.github.io/MultiMarkdown-4/tables).
## Images
Images can be specified in HTML by simply including the HTML in the
text. Alternatively, here are some short-hand notations:
* Image: ``
* Image with title attribute: ``
* Image with ID: `![Image description.][img_id]`
`[img_id]: img.png "This is a title" height=50px width=200px`
## Image sizes and responsive images
Add one line to `_config.yml`, and Dapper makes the images on every page
load faster:
images: true
* Each image of a PNG, JPEG, GIF or WebP file in the site gets `width` and
`height`, so the page doesn't jump about as images load.
* Images after the first on a page get `loading="lazy"`, so the browser
only fetches them as they scroll into view.
* JPEG and PNG images wider than 480, 960 or 1600 pixels are resized to
those widths (`photo-480w.jpg`, `photo-960w.jpg`, ...), and the image
gets a `srcset` listing them, so phones download small files.
* A WebP copy of each size is made too, and the image is wrapped in a
`` that offers it to browsers that support it.
This works for images in layouts as well as in pages. For a photo that is
2000 pixels wide, `` becomes:
Resizing needs [ImageMagick](https://imagemagick.org) (`brew install
imagemagick`) or [libvips](https://www.libvips.org) (`brew install vips`).
Without either, Dapper says so once, and still adds sizes and lazy
loading. Resized copies are kept in `.dapper/images`, so each is made only
once.
Each part can be set:
images:
dimensions: true # width and height
lazy: true # loading="lazy" after the first image
sizes: [480, 960, 1600] # widths to resize to; [] turns resizing off
webp: true # WebP copies
quality: 82 # JPEG and WebP quality
command: vips # magick, convert or vips (default: whichever is installed)
An image that has a `srcset` of its own, or is already inside a
``, keeps it. Images inside code blocks are left alone. Keep your
originals large; Dapper never makes an image bigger. `dapper check` warns
about [images without alt text](#check).
## Footnotes
Footnotes can be accomplished as follows:
```
Here is some text containing a footnote[^somesamplefootnote]. You can then
continue your thought...
[^somesamplefootnote]: Here is the text of the footnote itself.
This is an example of an inline footnote.[^This is the *actual* footnote.]
```
## Components
Components add things Markdown can't express (callouts, videos, galleries,
buttons, figures and maps) without any template code, so they're safe for
anyone writing content, people and AI assistants alike. A component starts
with three colons and its name. Most wrap Markdown and end with three colons
on their own line:
::: warning "Before you start"
Back up your site first. **Really.**
:::
::: details "Show all the opening hours"
- Monday to Friday: 9am to 6pm
- Saturday: 10am to 4pm
:::
::: gallery


:::
Others are a single line:
::: youtube https://www.youtube.com/watch?v=dQw4w9WgXcQ "Our story"
::: vimeo 76979871 "A short film"
::: button /contact/ "Get in touch"
::: figure shop.jpg "The shop at night" "Open until 9pm on Fridays"
::: map "1 Main Street, Springfield"
Component | What it makes
----------|--------------
`note`, `tip`, `info`, `warning`, `caution`, `important` | A box that stands out, with an optional title: `