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
Pod::POMto turn POD text into HTML.
turns the "content" into "output", by processing it through a templating engine. For example,
Papery::Renderer::Templatewill 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:
variables prefixed with a double underscore (
__) are internal to Papery and set by Papery. They cannot be overwritten by any of _config.yml, _meta.yml or the YAML front matter
variables prefixed with a single underscore (
_) are reserved for Papery, and can be overridden by any of _config.yml, _meta.yml or the YAML front matter
all the other variables are free to use by the web site itself.
Papery internal / reserved variables
The metadata variables recognized by Papery are:
The top-level source directory for the site
The top-level destination directory for the site
Papery::Analyzersubclass that will be used to analyze the source file.
A hash of extentions to
Papery::Processorsubclass that will be used to process text and generate the content.
Papery::Renderersubclass 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
Some of the analyzers, processors and renderers may also define their own variables.
Papery supports the following methods:
- new( $src, $dst )
Create a new
Paperyobject, 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_tree( $dir )
$diris relative to the source directory.
- process_file( $file )
$filefile, to generate one or more target files.
$fileis 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
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:
post_site hooks (for all those files we need to generate after the whole site has been generated)
not rebuilding files that don't need to be rebuilt
support for local _lib and _hooks directories
more analyzers (e.g.
Papery::Analyzer::Multiple) =item *
more processors (e.g.
more renderers (e.g.
You can find documentation for this module with the perldoc command.
You can also look for information at:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
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.