pelican-plugins/subcategory

#Subcategory Plugin#

This plugin adds support for subcategories in addition to article categories.

Subcategories are hierarchical. Each subcategory has a parent, which is either a regular category or another subcategory.

Feeds can be generated for each subcategory, just like categories and tags.

##Usage##

###Metadata###

Subcategories are an extension to categories. Add subcategories to an article's category metadata using a / like this:

Category: Regular Category/Sub-Category/Sub-Sub-category

Then create a subcategory.html template in your theme, similar to the category.html or tag.html templates.

In your templates, article.category continues to act the same way. Your subcategories are stored in the articles.subcategories list. To create breadcrumb-style navigation you might try something like this:

<nav class="breadcrumb">
<ol>
    <li>
        <a href="{{ SITEURL }}/{{ article.category.url }}">{{ article.category}}</a>
    </li>
{% for subcategory in article.subcategories %}
    <li>
        <a href="{{ SITEURL }}/{{ subcategory.url }}">{{ subcategory.shortname }}</a>
    </li>
{% endfor %}
</ol>
</nav>

###Subcategory folders###

To specify subcategories using folders you can configure PATH_METADATA
to extract the article path (containing all category and subcategory folders) into the subcategory_path metadata. The following settings would use all available subcategories for the hierarchy:

PATH_METADATA= '(?P<subcategory_path>.*)/.*'

You can limit the depth of generated subcategories by adjusting the regular expression to only include a specific number of path separators (/). For example, the following would generate only a single level of subcategories regardless of the folder tree depth:

PATH_METADATA= '(?P<subcategory_path>[^/]*/[^/]*)/.*'

##Subcategory Names##

Each subcategory's full name is a /-separated list of it parents and itself. This is necessary to keep each subcategory unique. It means you can have Category 1/Foo and Category 2/Foo and they won't interfere with each other. Each subcategory has an attribute shortname which is just the name without its parents associated. For example if you had…

Category/Sub Category1/Sub Category2

… the full name for Sub Category2 would be Category/Sub Category1/Sub Category2 and the "short name" would be Sub Category2.

If you need to use the slug, it is generated from the short name — not the full name.

##Settings##

Consistent with the default settings for Tags and Categories, the default settings for subcategories are:

'SUBCATEGORY_SAVE_AS' = os.path.join('subcategory', '{savepath}.html')
'SUBCATEGORY_URL' = 'subcategory/(fullurl).html'

savepath and fullurl are generated recursively, using slugs. So the full URL would be:

category-slug/sub-category-slug/sub-sub-category-slug

… with savepath being similar but joined using os.path.join.

Similarly, you can save subcategory feeds by adding one of the following to your Pelican configuration file:

SUBCATEGORY_FEED_ATOM = 'feeds/%s.atom.xml'
SUBCATEGORY_FEED_RSS = 'feeds/%s.rss.xml'

… and this will create a feed with fullurl of the subcategory. For example:

feeds/category/subcategory.atom.xml

Article urls can also use the values of subpath and suburl in their definitions. These are equivalent to the fullurl and savepath of the most specific subcategory. If you have articles that don't have subcategories these values are set to the category slug.

ARTICLE_SAVE_AS = os.path.join('{subpath}' 'articles' '{slug}.html')
ARTICLE_URL = '{suburl}/articles/{slug}.html'