nti.nikola-chameleon 1.0.0
NTI Nikola Chameleon
License: Apache
Requires Python: >=3.5
Keywords: nikola chameleon template blog static

======================
 nti.nikola_chameleon
======================

.. image:: https://img.shields.io/pypi/v/nti.nikola_chameleon.svg
        :target: https://pypi.python.org/pypi/nti.nikola_chameleon/
        :alt: Latest release

.. image:: https://img.shields.io/pypi/pyversions/nti.nikola_chameleon.svg
        :target: https://pypi.org/project/nti.nikola_chameleon/
        :alt: Supported Python versions

.. image:: https://travis-ci.org/NextThought/nti.nikola_chameleon.svg?branch=master
        :target: https://travis-ci.org/NextThought/nti.nikola_chameleon

.. image:: https://coveralls.io/repos/github/NextThought/nti.nikola_chameleon/badge.svg?branch=master
        :target: https://coveralls.io/github/NextThought/nti.nikola_chameleon?branch=master

.. image:: https://readthedocs.org/projects/ntinikola_chameleon/badge/?version=latest
        :target: https://ntinikola_chameleon.readthedocs.io/en/latest/
        :alt: Documentation Status

An extremely flexible template system for the `Nikola
<https://pypi.python.org/pypi/Nikola>`_ static blog system using
`Chameleon <https://pypi.python.org/pypi/Chameleon>`_, `z3c.pt
<https://pypi.python.org/pypi/z3c.pt>`_ and `z3c.macro
<https://pypi.python.org/pypi/z3c.macro>`_

A basic template using this system is available in `base-chameleon
<https://github.com/NextThought/nti.nikola_themes.base-chameleon>`_,
and an extension of that using bootstrap3 is available in
`bootstrap3-chameleon
<https://github.com/NextThought/nti.nikola_themes.bootstrap3-chameleon>`_.

Documentation is hosted at https://ntinikola_chameleon.readthedocs.io/

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

Nikola uses a `custom mechanism <https://pypi.python.org/pypi/yapsy>`_
to find plugins instead of using the usual ``pkg_resources`` system.
That makes it *incredibly* difficult to install plugins; it's not enough
just to ``pip install`` a package from PyPI. Instead, you must *also*
copy a ``.plugin`` file to a particular location on disk. This can be:

- ~/.nikola/plugins/
- The ``plugins`` directory of your Nikola site.

Beside that '.plugin' file there must also be a '.py' file of the same
name that the plugin lists as a module (yes, even though the plugin file
specifically requests a Python module, yapsy requires that it be a
file or directory beside the plugin file---so not really a module).

It's ridiculous to require everyone to copy plugins into their plugin
folder (they're not even correctly on ``sys.path``, meaning that
zope.configuration and many other tools won't work) and we don't plan
to let Nikola do that automatically (we're not on the Nikola plugin
index and won't be until they let us do standard installs), so the
best we can do is attempt to workaround yapsy's limitations.

Into your site's plugin directory, place the following .py file::

  # nti_nikola_chameleon.py
  from nti.nikola_chameleon import *


Beside that, you'll need a ``nti.nikola_chameleon.plugin`` file::

  # -*- mode: conf; -*-
  [Core]
  Name = nti.nikola_chameleon
  Module = nti_nikola_chameleon

  [Documentation]
  Author = NextThought
  Version = 1.0
  Website = https://github.com/NextThought/nti.nikola_chameleon
  Description = Support for Chameleon ZPT templates.

  [Nikola]
  PluginCategory = Template


=========
 Changes
=========

1.0.0 (2018-05-26)
==================

- Posts that have a true value for ``has_math`` will now implement
  the ``IMathJaxPost`` interface when used as the context.
- Index pages that have any posts using MathJax will now have a
  context object that implements ``IMathJaxPostList``.
- Add a view for getting CSS data. Currently it has
  ``context/@@post_css/pagekind_class``.
- Update to Nikola 8; drop support for Python 2.7.
- Add ``interfaces.IRootPage`` which is added to pages for which the
  metadata field ``nti-extra-page-kind`` is set to ``root``.
- Make the ``featured`` list available to all pages, not just index
  pages. Together with the IRootPage this can be used to promote blog
  posts to the root index.html.
- Add ``embedded_content`` to the ``@@post_text`` view.
- Initial support for template-based shortcodes. See
  https://github.com/NextThought/nti.nikola_chameleon/issues/5

0.0.1a2 (2017-10-14)
====================

- Map the Nikola ``messages`` function onto the native ``i18n``
  functionality of Chamleon. Attributes like ``i18n:translate`` are
  now preferred to explicit calls to ``options/messages`` when
  possible.

- Add support for viewlets. Several default viewlet managers are
  supplied, and a ZCML directive ``<browser:newViewletManager>`` is
  provided so themes can create new viewlet managers::

    <browser:newViewletManager id="ILeftColumn" />
    <browser:viewletManager
        name="left_column"
        provides=".viewlets.ILeftColumn" />

- Add a path adapter to easily get formatted dates from a post, either
  a static format (``post/formatted_date:webiso``) or dynamically from
  a variable (``post/formatted_date:?date_format``).

- Add a view to get the text of a post, respecting teaser settings:
  ``post/@@post_text/content``.

- Move feed support to a ``@@feeds`` view for headers, and a viewlet
  for body::

   <browser:viewlet
      name="feed_content_header"
      manager=".interfaces.IHtmlBodyContentHeaderViewletManager"
      class=".feeds.HTMLFeedLinkViewlet"
      layer=".interfaces.IAuthorPageKind"
      permission="zope.Public"
      weight="1"
      classification_name="author"
      />

- Add a view interface (``ICommentKind``) for comment systems. Only Disqus is
  currently supported. Note that this may move in the future to be a layer.

0.0.1a1 (2017-10-09)
====================

- Preliminary PyPI release. While this package is functional, it is
  not yet documented sufficiently to be of general use. It is also not
  expected to be fully stable.