# Dapper [![test](https://github.com/markdbenson/dapper/actions/workflows/test.yml/badge.svg)](https://github.com/markdbenson/dapper/actions/workflows/test.yml) [![CPAN](https://img.shields.io/cpan/v/App-Dapper.svg)](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: `![The team](team.jpg)`. `![](team.jpg)` 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 ---

Recent posts

[% FOR post IN paginator.items %]

[% post.title | html %]

[% post.date.strftime('%d %B %Y') %]

[% post.excerpt %]

Read more

[% 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 ---

Name

[% page.name %]

Menu

Fruits

    [% for fruit in page.fruits %]
  • [% fruit %]
  • [% end %]
``` 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 description.](img.png)`
* Image with title attribute: `![Image description.](img.png "This is a title")`
* 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, `![The shop](shop.jpg)` becomes:

    
    The shop

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
    ![The shop](shop.jpg)
    ![The team](team.jpg)
    :::

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: `