App-Dapper
view release on metacpan or search on metacpan
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 at the start of the file.
2. The *layout* configuration specifies which layout to use.
3. The `index` layout indicates that `_layout/index.html` should be used.
4. The `title` configuration is the name of the post/page. It is optional.
5. All of the configurations may be used in the corresponding layout file.
<!-- Example use of "name" in a layout file -->
[% page.name %]
**_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:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>[% page.title %]</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
</head>
<body>
[% page.content %]
</body>
</html>
The main content of the text file that is being rendered with this template
is available using `[% page.content %]`.
Definitions specified in the `_config.yml` file can be referenced under the
"site" namespace (e.g. `[% site.name %]`. Definitions specified in the 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:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Welcome</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
</head>
<body>
<p>Hello world.</p>
</body>
</html>
# 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 `<key>:<value>`
pairs or arrays, arranged hierarchically:
# Dapper config file
---
name: Mark Benson Portfolio
url: http://markbenson.io/
source : _source/
output : _output/
layout : _layout/
links :
Preface : /preface/
Amazon : http://amazon.com/author/markbenson
Github : http://github.com/markdbenson
LinkedIn : http://linkedin.com/in/markbenson
Twitter : https://twitter.com/markbenson
ignore :
- ^\.
- ^_
- ^design$
- ^README.md$
- ^Makefile$
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 %]
Dapper may be used as a perl module directly from a script. Examples:
use App::Dapper;
# Create a Dapper object
my $d = App::Dapper->new();
# Initialize a new website in the current directory
$d->init();
# Build the site
$d->build();
# Serve the site locally at http://localhost:8000
$d->serve();
After installing Dapper, you can find documentation for this module with the
perldoc command.
perldoc App::Dapper
# Appendix B: Debugging
With templating, it's easy to outsmart yourself and forget what variables are
assigned to which collection and how that collection should be used in a
template. Here is a way to debug that makes use of the `json` template filter
built in to Dapper. The resulting page that we'll create displays all of the
varialbes that are available for you to use.
First, create a debug page in your `_source` directory:
$ echo "" > _source/debug/index.html
Then, edit the file and fill it with this content:
```html
---
name: Debug
layout: plain
---
<!DOCTYPE html>
<html lang="en">
<head>
<title>Dapper Debug</title>
<style type="text/css" media="screen">
#editor {
position: absolute;
top: 0;
right: 0;
bottom: 0;
left: 0;
}
</style>
</head>
<body>
<div id="editor">[% dump site | json(1)%]</div>
<script src="//cdnjs.cloudflare.com/ajax/libs/ace/1.1.3/ace.js"
type="text/javascript" charset="utf-8"></script>
<script>
var editor = ace.edit("editor");
editor.setTheme("ace/theme/text_mate");
editor.getSession().setMode("ace/mode/json");
editor.setReadOnly(true);
window.setTimeout(function() {
editor.getSession().foldAll(2,editor.session.getLength());
}, 100);
</script>
</body>
</html>
```
Create a plain layout template:
$ echo "[% page.content %]" > _layout/plain.html
Then, build your site and view the content locally at http://localhost:8000/debug/
# Appendix C: Internals
There are two importatn aspects of Dapper internals that are important
to understand. The first is that source files are rendered using the
templating system once, and then again after being combined with
a layout. This means that layout variables and directives can be used in source
files.
The second important thing to understand about Dapper internals is that
after all of the source files are rendered to output, Dapper does a
copy operation which copies things like binary files, images, or other
files that need to be transferred into the output directory but do not
need to be processed by Markdown or the templating system. The rules for what to
copy are simple: everything is copied except for those things that match the
site.ignore list. By default, the following ignore list is used:
```
ignore :
- ^\.
- ^_
- ^dapper$
```
More files and regular expression patterns may be specified in the project
configuration file. For instance, if you have a folder that holds your
design files and is called `design`, you might not want to have that copied
into the output directory. In this case, you would add the following lines
to your `_config.yml` file:
```
ignore :
- ^design$
```
# Appendix D: Meta
Dapper development environment:
* perlbrew on osx to isolate and test against different versions of Perl
# Author
( run in 1.449 second using v1.01-cache-2.11-cpan-39bf76dae61 )