Template API for categories.
category object provides the following:
path: The full path to the category
basename: Just the last part of the category path
name: A display name for the category.
This defaults to taking the category basename, converting
_s to spaces, and then title-casing the name. For example, the category
some/long/category_namewill have a default name of
"Category Name". This can be overridden using a meta file.
Optionally takes HTML processing arguments.
subcats: The subcategories of this category. Takes the following argument:
recurse: Whether to include the subcategories of the subcategories, and their subcategories and so on. Possible values:
False: Only include direct subcategories (default)
True: Include all subcategories
parent: The parent category, if any
link: The link to the category; optionally takes the following arguments:
template: Which template to use when rendering the category
absolute: Whether to format this as an absolute or relative URL
False: Use a relative link (default)
True: Use an absolute link
first: Returns the first entry in this category; optionally takes view arguments
last: Returns the last entry in this category; optionally takes view arguments
lastwill potentially point to entries for which the user is not authorized. If that matters, use
get: Get a header defined in the meta file
get_all: Get all instances of a meta file header as a list
sort_name: The name used for sorting
root: The root category of the blog, useful for storing site-level metadata (such as the site name or global configuration).
This is roughly equivalent to
category.breadcrumb, but is slightly more efficient and easier to type.
This can take optional view arguments, such as
There are multiple ways to access the tag information, depending on preference; for example, you can separate them in the loop:
or you can get at them directly:
This does not provide any built-in sorting; you can use Jinja’s
sortfilter for that:
If you want the tags to display based on a
viewyou can pass in
**view.specas the argument list; for example, this snippet will override the page’s view to require all tags to be present, and print a refinement list of tags:
The following properties are also available but probably aren’t of use to template authors, and are only listed for the sake of completion. You should not rely on them for anything as they might change without warning.
file_path: The file path of the category’s metadata file
aliases: The various registered path aliases for this category
Example template code for printing out an entire directory structure (flattened):
Example template code for printing out the directory structure in a nice recursive manner:
Categories can also be compared to other categories, which is useful for determining if a subcategory is the same as this one. This snippet will show all of the categories on the website, with the currently-visible one getting a class of
here and any parent categories getting a class of
Category data can be added using a metadata file, which is simply a file whose name ends in
.meta and lives somewhere
in the content directory. Similarly to entry files, this will default to using its place in the
content directory for the category to use, but this can also be overridden using a
The headers supported by Publ itself:
Category: Specifies which category this file refers to
Name: Overrides the friendly/display name of the category (i.e.
Index-Template: Use this template instead of
indexwhen rendering this category (useful if you want to override a category or site’s index template without overriding its subcategories)
Entry-Template: Use this template instead of
entrywhen rendering an entry
Sort-Name: The name to use when sorting this in a subcategory list
Path-Alias: Redirects an unused path to this category; can optionally take a template parameter
Path-Mount: Display an otherwise-unused path as if it’s a view of this category; can optionally take a template parameter
For example, given the file
it will set the
name attribute of the
some/category category to
"Random Category". However, if the file contains:
then it will set the
name attribute of the
other/category category to
Similarly to entries, this also supports the
Path-Mount headers; for example:
will redirect requests to
/comics/cat-sketchbook.php to the
/art/sketchbook category using the
archive template (i.e. a path like
/art/sketchbook/archive), and requests to
/sketchbook will render this category using the default template (without redirecting).
You can also define any other arbitrary values you like, which will then be put on the category object, and which are
accessible directly via
get_all. The behavior is the same as on entry files.
Any text after the headers will be treated as the
description for the category. Markdown is supported.
Note that at least one header is required. If you just want to provide a description and no other configuration, you can simply start the file with a blank line, or you can use a bogus header, for example:
If you want to change the order of subcategories in a subcategory list, that is easy to do with the
Sort-Name property; for example, if you have categories named
baz which you want to appear in that order, you can do something like:
in their respective categories.