Introduction
============

PopPage is a simple command-line utility originally intended as a static
website generator but has since grown into a
`cookiecutter <https://github.com/audreyr/cookiecutter>`__ clone. The
main features of PopPage are:

-  Uses `Jinja2 templates <http://jinja.pocoo.org/>`__ to generate
   output.

-  Uses YAML to store default key/values for template variables.

-  Output can be single files or directories.

-  Key/values applied to the templates variables can specified on the
   command line.

Status
======

Currently, this project is in the **development release** stage. While
this project is suitable for use, please note that there may be
incompatibilities in new releases.

Release notes are maintained in the project
`changelog <https://github.com/jeffrimko/PopPage/blob/master/CHANGELOG.adoc>`__.

Requirements
============

PopPage should run on any Python 2.7/3.x interpreter without additional
dependencies.

Usage
=====

PopPage can be run from the command line using ``poppage``. Type
``poppage --help`` for usage information.

Some Important Notes
--------------------

Before showing any examples, keep these notes in mind:

-  Template file/directory names can contain template variables (e.g.
   ``{{foo}}.txt``). The provided key/values will be used for the output
   file generation unless an explicit OUTPATH is provided.

-  The output will be passed to ``stdout`` if INPATH is a file (rather
   than a directory) and INPATH does not contain a template variable and
   no OUTPATH is specified.

CLI Key/Values
--------------

The following is a quick example of using PopPage from the CLI:

-  Template file (``template.jinja2``):

   ::

       Hello {{name}}!

-  PopPage command:

   ::

       poppage make template.jinja2 --string name world

-  Output to ``stdout``:

   ::

       Hello world!

YAML Key/Values
---------------

Additionally, default key/values can be stored in a YAML file:

-  Template file (``template.jinja2``):

   ::

       Hello {{name}}!

-  Defaults file (``defaults.yaml``):

   ::

       name: sun

-  PopPage command:

   ::

       poppage make template.jinja2 --defaults defaults.yaml

-  Output to ``stdout``:

   ::

       Hello sun!

Custom YAML Tags
----------------

The following custom YAML tags are provided:

-  ``!file`` - Reads value from a file.

-  ``!cmd`` - Reads value from a CLI command output.

Check out this example:

-  Template file (``template.jinja2``):

   ::

       Hello {{first}} {{last}}!

-  Defaults file (``defaults.yaml``):

   ::

       first: !file myfile.txt
       last: !cmd python -c "print('Skywalker')"

-  Content of ``myfile.txt``:

   ::

       Anakin

-  PopPage command:

   ::

       poppage make template.jinja2 --defaults defaults.yaml

-  Output to ``stdout``:

   ::

       Hello Anakin Skywalker!

Similar
=======

The following projects are similar and may be worth checking out:

-  `cookiecutter <https://github.com/audreyr/cookiecutter>`__
