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.
outdir option will determine the output directory.
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
If a tilde character (
~) is supplied,
it will be expanded to the user’s home directory.
with_blog option set to
enable the blog extension.
See Blog extension for setup information.
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.,
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.