Configuration¶
handroll supports an optional handroll.conf
file that can be stored at the
root of the site’s directory. This ini
style file provides configuration
information that handroll will use while generating the output. For example:
[site]
outdir = ~/mblayman.github.io
Arguments provided on the command line will override the equivalent configuration file option.
site
section¶
The outdir
option will determine the output directory.
The outdir
permits relative paths.
One useful pattern with relative paths
is to set outdir = ..
as the value.
Source and output can exist
in a single repository or directory.
Putting the output at the root of a repository
makes it easy to deploy the entire project as a website.
When generating output
or watching the source directory,
handroll is aware of the source and
allows the two directories to coexist
without interference.
If a tilde character (~
) is supplied,
it will be expanded to the user’s home directory.
The with_blog
option set to true
, on
, yes
, or 1
will
enable the blog extension.
See Blog extension for setup information.
Front matter¶
Source documents like Markdown files can have additional data added to them. This data is stored in a front matter section at the top of a source document. handroll will read the extra data and pass it along to the template. In the template, the data will be accessible by whatever name was provided. An example Markdown source document would look like:
---
title: A Sample Site Title
bonus: It's a secret to everybody.
---
## Another heading
This is text in the body.
You may also include the YAML directive (e.g., %YAML 1.1
).
The following example is equally valid.
%YAML 1.1
---
title: A Sample Site Title
bonus: It's a secret to everybody.
---
## Another heading
This is text in the body.
Note: When using front matter, handroll does not infer the title from the first line of the document. If a title is desired, the attribute must be explicitly added to the front matter.