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.
Papery
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.
Papery::Processor::Pod::POM
Pod::POM
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.
Papery::Renderer::Template
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.
Papery::Pulp
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.
The 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.
Papery::Analyzer
A hash of extentions to Papery::Processor classes
Papery::Processor
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
Papery::Renderer
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.
__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
$dir is relative to the source directory.
Process the $file file, to generate one or more target files.
$file
$file is relative to the source directory.
Philippe Bruhat (BooK), <book at cpan.org>
<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/>).
ttree
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.
bug-papery at rt.cpan.org
Here's a list of some of the things ahead:
post_(analyze|process|render) hooks
post_site hooks (for all those files we need to generate after the whole site has been generated)
file copy
not rebuilding files that don't need to be rebuilt
dependencies
support for local _lib and _hooks directories
more analyzers (e.g. Papery::Analyzer::Multiple) =item *
Papery::Analyzer::Multiple
more processors (e.g. Text::Markdown)
Text::Markdown
more renderers (e.g. Text::Template
Text::Template
You can find documentation for this module with the perldoc command.
perldoc Papery
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Papery
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Papery
CPAN Ratings
http://cpanratings.perl.org/d/Papery
Search CPAN
http://search.cpan.org/dist/Papery
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.
To install Papery, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Papery
CPAN shell
perl -MCPAN -e shell install Papery
For more information on module installation, please visit the detailed CPAN module installation guide.