minchin.pelican.jinja-filters 1.1.0
Jinja Filters for Pelican.
License: MIT License

=============
Jinja Filters
=============

*Deprecation Notice*: This plugins is now being maintained as part of the
`Pelican-Plugins <https://github.com/pelican-plugins>`_ organization on GitHub.
The new code repo is at `GitHub.com/pelican-plugins/jinja-filters
<https://github.com/pelican-plugins/jinja-filters>`_. The new PyPI package is
at *pelican-jinja-filters* (for your ``requirements.txt``) and the new plugin
name is *pelican.plugins.jinja_filters* (to update ``PLUGINS`` in your
``pelicanconf.py``).

Old Readme
==========

``Jinja Filters`` is a plugin for `Pelican <http://docs.getpelican.com/>`_,
a static site generator written in Python.

``Jinja Filters`` provides a selection of functions (called *filters*) for
templates to use when building your website. They are packaged for Pelican, but
may prove useful for other projects that make use of
`Jinja2 <http://jinja.pocoo.org/>`_.


Installation
============

The easiest way to install ``Jinja Filters`` is through the use of pip. This
will also install the required dependencies (currently ``pelican`` and
``titlecase``) automatically.

.. code-block:: sh

  pip install minchin.pelican.jinja_filters

Then, in your ``pelicanconf.py`` file, add ``Jinja Filters`` to your list of
plugins:

.. code-block:: python

  PLUGINS = [
              # ...
              'minchin.pelican.jinja_filters',
              # ...
            ]

And that's it! The filters are now available for use in your templates.


Usage
=====

At present, the plugin includes the following filters:

- ``datetime`` |--| allows you to change to format displayed for a datetime
  object. Optionally supply a `datetime format string
  <https://docs.python.org/3.6/library/datetime.html#strftime-and-strptime-behavior>`_
  to get a custom format.
- ``article_date`` |--| a specialized version of ``datetime`` that returns
  datetimes as wanted for article dates; speciefically
  *Friday, November 4, 2016*.
- ``breaking_spaces`` |--| replaceds non-breaking spaces (HTML code *&nbsp*)
  with normal spaces.
- ``titlecase`` |--| Titlecases the supplied string

For example, within your theme templates, you might have code like:

.. code-block:: html+jinja

    <span class="published">
        Article Published {{ article.date | article_date }}
    </span>

gives::

    Article Published Friday, November 4, 2016

Or with your own dateformat:

.. code-block:: html+jinja

    <span class="published">
        Article Published {{ article.date | datetime('%b %d, %Y') }}
    </span>

gives::

    Article Published Nov 04, 2016

Fitlers can also be chained, or applied in sequence. For example to remove
breaking spaces and then titlecase a catgory name, you might have code like:

.. code-block:: html+jinja

    <a href="{{ SITEURL }}/{{ article.category.url }}">
        {{ article.category | breaking_spaces | titlecase}}
    </a>


Known Issues
============

- the ``setup.py`` file for this project does not run on Python 2.7. However,
  wheels of this project are "universal" and so can be generated by Python 3
  and subsequently installed by Python 2.7.


License
=======

``Jinja Filters`` is under the MIT License. See attached ``License.txt`` for
full license text.


.. |--| unicode:: U+2013   .. en dash