App-Dapper
view release on metacpan or search on metacpan
--------------|-------------------------------------|---------------------------------------------
`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:
<a href="[% site.url %]">[% site.name %]</a>
The links (key/value pairs) can be listed like this:
[% for link in site.links %]
<a href="[% link.value %]">[% link.key %]</a><br />
[% end %]
All of the items in the `ignore` array can be shown like this:
<ul>
[% for i in site.ignore %]
<li>[% i %]</li>
[% end %]
</ul>
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
( run in 0.917 second using v1.01-cache-2.11-cpan-234fa220139 )