Papery - The thin layer between what you write and what you publish
Below is a significant excerpt of the papery command-line tool:
use Papery;
# generate the site
Papery->new( @ARGV )->generate();
Papery is meant to be a very thin layer between a number of Perl modules that you can use to generate the files of a static web site.
It is intended to make it very flexible, so that it's easy to add hooks and specialized modules to generate any file that is needed for the site.
Papery processes entire directory trees containing files and templates, and for each file that is not ignored, it will run the follwing steps:
splits the file between "metadata" and "text", and creates one or more objects encapsulating those (everything is basically a hash, and the text is just some special metadata)
turns the "text" into "content" by parsing it with a given processor. For example Papery::Processor::Pod::POM uses Pod::POM to turn POD text into HTML.
turns the "content" into "output", by processing it through a templating engine. For example, Papery::Renderer::Template will use Template Toolkit to process the main template and produce the target file.
Each step takes a Papery::Pulp object, which is basically a hash of metadata. Each step can return more than one Papery::Pulp object. After the rendering step, each Papery::Pulp object is saved to a file.
Initial meta information comes from the global configuration (top-level _config.yml file). It is then updated from the _meta.yml file in the current directory.
Furthermore, each file can contain metadata for itself, using "YAML Front Matter":
---
# this is actually YAML
title: Page title
---
This is the actual content
The metadata comes in three kinds:
__) are internal to Papery and set by Papery. They cannot be overwritten by any of _config.yml, _meta.yml or the YAML front matter_) are reserved for Papery, and can be overridden by any of _config.yml, _meta.yml or the YAML front matterThe metadata variables recognized by Papery are:
The top-level source directory for the site
The top-level destination directory for the site
The Papery::Analyzer subclass that will be used to analyze the source file.
A hash of extentions to Papery::Processor classes
The Papery::Processor subclass that will be used to process text and generate the content.
The Papery::Renderer subclass that will be used to render the content and create the output
The text resulting from the analysis step.
The content resulting from the processing step.
The output resulting from the rendering step.
The final destination for the output. The filename is relative to __destination.
Some of the analyzers, processors and renderers may also define their own variables.
Papery supports the following methods:
Create a new Papery object, with the provided source and destination directories.
Process all the files in the source directory and generate the resulting files in the destination directory.
Process the $dir tree.
$dir is relative to the source directory.
Process the $file file, to generate one or more target files.
$file is relative to the source directory.
Philippe Bruhat (BooK), <book at cpan.org>
Much of the inspiration for this module comes from Jekyll (http://jekyllrb.com/) and Template Toolkit's ttree (http://www.template-toolkit.org/>).
While my initial goal was to be able to write a web site in POD, I realized that any format can be turned into HTML and no limitation on the source format should be imposed on the people. Same goes for the templating engine. My plan is to make this flexible enough (using hooks) that one can extend it easily to build any kind of website.
Please report any bugs or feature requests to bug-papery at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Papery. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
Here's a list of some of the things ahead:
Papery::Analyzer::Multiple) =item *
more processors (e.g. Text::Markdown)
Text::TemplateYou can find documentation for this module with the perldoc command.
perldoc Papery
You can also look for information at:
Copyright 2010 Philippe Bruhat (BooK), all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
