This Pelican plugin adds support for multiple categories per article and nested categories. It requires Pelican 4.2.0 or newer.
The example directory contains a minimal Pelican web site that can be used for testing.
This plugin can be installed via:
python -m pip install pelican-more-categories
As long as you have not explicitly added a PLUGINS setting to your Pelican settings file, then the newly-installed plugin should be automatically detected and enabled. Otherwise, you must add more_categories to your existing PLUGINS list. For more information, please see the How to Use Plugins documentation.
To indicate that an article belongs to multiple categories, use a comma-separated string:
Category: foo, bar, bazz
This will add the article to the categories foo, bar, and bazz.
Existing themes that use article.category will display only the first of
these categories, foo. This plugin adds article.categories that you can
loop over instead. To accommodate this plugin in a theme whether it is present
or not, use:
{% for cat in article.categories or [article.category] %}
<a href="{{ SITEURL }}/{{ cat.url }}">{{ cat }}</a>{{ ', ' if not loop.last }}
{% endfor %}(This is a re-implementation of the subcategory plugin.)
To indicate that a category is a child of another category, use a slash-separated string:
Category: foo/bar/bazz
This will add the article to the categories foo/bar/bazz, foo/bar and
foo.
Existing themes that use article.category will display the full path to the
most specific of these categories, foo/bar/bazz. For any category cat, this
plugin adds cat.shortname, which in this case is bazz, cat.parent, which
in this case is the category foo/bar, and cat.ancestors, which is a list of
the category’s ancestors, ending with the category itself. For instance, to
also include a link to each of the ancestor categories on an article page, in
case this plugin in present, use:
{% for cat in article.category.ancestors or [article.category] %}
<a href="{{ SITEURL }}/{{ cat.url }}">{{ cat.shortname or cat }}</a>{{ '/' if not loop.last }}
{% endfor %}Likewise, category.shortname, category.parent, and category.ancestors can
also be used on the category template.
Additionally, this plugin adds category.children: a list of categories
that have category as a parent.
{% for child in category.children %}
<a href="{{ SITEURL }}/{{child.url}}">{{child.shortname|capitalize}}</a>
{% endfor %}If you need all descendent children and not just the immediate children, you can use the list of descendent children: category.descendents
The slug of a category is generated recursively by slugifying the short name of the category and its ancestors (preserving slashes):
slug-of-(foo/bar/baz) := slug-of-foo/slug-of-bar/slug-of-baz
To specify categories using the directory structure, you can configure
PATH_METADATA to extract the article path into the category metadata. The
following settings would use the entire structure:
PATH_METADATA = "(?P<category>.*)/.*"If you store all articles in a single articles/ folder that you want to
ignore for this purpose, use:
PATH_METADATA = "articles/(?P<category>.*)/.*"The list categories of all pairs of categories with their corresponding
articles, which is available in the context and can be used in templates (e.g.
to make a menu of available categories), is ordered lexicographically, so
categories always follow their parent:
aba
aba/dat
abaala
Contributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on existing issues.
To start contributing to this plugin, review the Contributing to Pelican documentation, beginning with the Contributing Code section.
This project is licensed under the AGPL-3.0 license.