Site Preprocessors

Categories Manager

Inspects pages for categories and populates node.categories with a list of dictionaries containing:

• name : the name of the category
• posts : the list of posts belonging to the category
• feed_url : the url category’s feed
• post_count : the number of posts in the category

Can optionally generate a per-category list of all posts from a template you provide, plus a list of all categories.

Configuration

Categories have a many-to-many relationship with pages. Pages list the categories they belong to in their {% hyde %} section, e.g.

{% hyde
  title: "Parrot Sketch"
  categories: ["parrot", "mortality"]
%}
...

then the preprocessor walks all pages collecting their categories properties. <node>.categories will contain the collected list of dictionaries. Other actions depend on keys in settings.py:

LAYOUT_DIR = "..."
#CATEGORY_ARCHIVES_DIR = "archives"
SITE_PRE_PROCESSORS = {
    'blog': {
        'hydeengine.site_pre_processors.CategoriesManager' : {
            # blog.categories gets populated even if there are no other
            # settings here.

            # Key 'archiving':
            #
            # Whether to produce any lists --- per-category lists of posts and
            # perhaps an all-category list.
            #
            # Optional.  Default: False
            #
            # If True, category templates (configured below) will be expanded
            # to produce pages.
            #
            # If False, blog.categories gets populated as usual but nothing
            # else happens (no output is produced, even if template
            # names/output directories are configured).
            #
            # Presumably called 'archives' because one application of
            # categories is to put every blog in a category named after the
            # year it got posted.
            'archiving': True,

            # Key 'template':
            #
            # The template to expand once per unique category, relative to
            # LAYOUT_DIR.
            #
            # Mandatory if archiving is True.
            #
            # Gets passed 'posts' and 'categories'.  Typically you'll code this
            # template to expand to a list of all pages in the given category.
            # Depending on whether you use clean URLs, produces either:
            #    <category>.html
            # or:
            #    <category>/index.html
            # for each category.
            'template': '_per-category.html',

            # Key 'output_folder'
            #
            # The directory to write per-unique-category pages to.
            #
            # Optional.  Default: the value of CATEGORY_ARCHIVES_DIR if set,
            # else the string 'archives'.
            'output_folder': 'category',

            # Key 'listing_template':
            #
            # The template to expand just once.
            #
            # Optional.  Default: not generated
            #
            # Gets passed 'categories'.  Typically used to generate a list of
            # all categories.  You can achieve the same thing in any page
            # without this by obtaining a reference to <node>.categories,
            # perhaps with the help of the node injection preprocessor.
            'listing_template': '_category-index.html',

            # Key 'meta':
            #
            # A dictionary of category metadata, typically used to describe
            # each category.
            #
            # Optional.  Default: no extra properties are set
            #
            # Any key-value pairs set here can be accessed as siblings of the
            # automatic properties (category.name, category.posts) e.g. as
            # category.description.
            'meta': {
                'parrot': {
                    'description': "Posts related to parrots such as the Norweigan Blue",
                },
                'mortality': {
                    'description': "Posts that remind us how fragile life is",
                },
            },
        },
    },
}          

_per-category.html

This gets rendered for each category.

{% hyde
    listing: true
%}
<div id="archives">
<ul>
{% for post in posts %}
    <li>
      <a href="{{post.url}}">{{post.title}}</a>
    </li>
{% endfor %}
</ul>
</div>

As you can see the posts variable — the collection of posts in the current category — is provided to the template. In addition the categories is also provided as a shortcut to the list of dictionaries (see Categories Manager section). The Category object is defined in site_pre_processors.py.

_category-index.html

The ‘listing_template’ template receives the categories variable on which you can loop to reference every category defined on your blog.

<h1>List of categories</h1>
<ul>
  {% for c in categories %}
  <li><a href="{{c.archive_url}}">{{c.name}}</a></li>
  {% endfor %}
</ul>

Node Injector

Injects a node identified by the given path as the value of the given context variable for all the pages in the specified node.

Configuration

The following configuration injects the blog node (/content/blog) as blog_node variable into all the pages in the content folder.

SITE_PRE_PROCESSORS = {
    '/': {
        'hydeengine.site_pre_processors.NodeInjector' : {
               'variable' : 'blog_node',
               'path' : 'content/blog'
        }
    }
}