Module

`rendering.template_functions.taxonomies`

Taxonomy helper functions for templates.

Provides functions for working with tags, categories, and related content, plus normalized TagView for consistent tag data access in templates.

Architecture:

Core functions (tag_url, related_posts, etc.) are pure Python with no engine dependencies. Context-dependent functions like tag_url_with_site are registered via the adapter layer for engine-specific context handling.

Example (TagView): {% for tag in site | tag_views %} {{ tag.name }} ({{ tag.count }}) {% end %}

Classes

TagView 7 ▼

Normalized view of a tag for templates. Provides consistent access to tag data including name, slu…

Normalized view of a tag for templates.

Provides consistent access to tag data including name, slug, URL, post count, and optional description.

Attributes

Name	Type	Description
`name`	`str`	Display name of the tag
`slug`	`str`	URL-safe slug
`href`	`str`	URL to tag page
`count`	`int`	Number of posts with this tag
`description`	`str`	Tag description (if available)
`percentage`	`float`	Percentage of total posts (for tag clouds)

Methods

from_taxonomy_entry 3 TagView ▼

Create a TagView from a taxonomy entry.

classmethod

def from_taxonomy_entry(cls, slug: str, tag_data: dict[str, Any], total_posts: int = 0) -> TagView

Parameters

Name	Type	Description
`slug`	`—`	Tag slug
`tag_data`	`—`	Tag data dict with 'name', 'pages', etc.
`total_posts`	`—`	Total number of posts for percentage calculation Default:`0`

Returns

TagView Normalized TagView instance

Functions

register 2 None ▼

def register(env: TemplateEnvironment, site: SiteContent) -> None

Context-dependent functions (tag_url) are registered via the adapter layer which handles engine-specific context mechanisms.

Non-context functions (related_posts, popular_tags, has_tag) are registered directly here.

Parameters

Name	Type	Description
`env`	`TemplateEnvironment`
`site`	`SiteContent`

tag_views_filter 3 list[TagView] ▼

Get all tags as normalized TagView objects.

def tag_views_filter(source: Any, limit: int | None = None, sort_by: str = 'count') -> list[TagView]

Parameters

Name	Type	Description
`source`	`Any`	Site object or taxonomies dict
`limit`	`int \| None`	Maximum number of tags to return (None for all) Default:`None`
`sort_by`	`str`	Sort field ('count', 'name', 'percentage') Default:`'count'`

Returns

list[TagView]

tag_view_filter 1 TagView | None ▼

Get a single tag as a TagView by slug.

def tag_view_filter(tag_slug: str) -> TagView | None

Parameters

Name	Type	Description
`tag_slug`	`str`	Tag slug to look up

Returns

TagView | None

related_posts 3 list[Any] ▼

Find related posts based on shared tags. PERFORMANCE NOTE: This function now u…

def related_posts(page: Any, all_pages: list[Any] | None = None, limit: int = 5) -> list[Any]

Find related posts based on shared tags.

PERFORMANCE NOTE: This function now uses pre-computed related posts for O(1) access. The old O(n²) algorithm is kept as a fallback for backward compatibility with custom templates.

RECOMMENDED: Usepage.related_postsdirectly in templates instead of calling this function.

Parameters

Name	Type	Description
`page`	`Any`	Current page
`all_pages`	`list[Any] \| None`	All site pages (optional, only needed for fallback) Default:`None`
`limit`	`int`	Maximum number of related posts Default:`5`

Returns

list[Any]

popular_tags 2 list[tuple[str, int]] ▼

Get most popular tags sorted by count.

def popular_tags(tags_dict: dict[str, list[Any]], limit: int = 10) -> list[tuple[str, int]]

Parameters

Name	Type	Description
`tags_dict`	`dict[str, list[Any]]`	Dictionary of tag -> pages
`limit`	`int`	Maximum number of tags Default:`10`

Returns

list[tuple[str, int]]

tag_url 1 str ▼

Generate URL for a tag page. Uses bengal.utils.text.slugify for tag slug gener…

def tag_url(tag: str) -> str

Generate URL for a tag page.

Uses bengal.utils.text.slugify for tag slug generation.

Parameters

Name	Type	Description
`tag`	`str`	Tag name

Returns

str

has_tag 2 bool ▼

Check if page has a specific tag.

def has_tag(page: Any, tag: str) -> bool

Parameters

Name	Type	Description
`page`	`Any`	Page to check
`tag`	`str`	Tag to look for

Returns

bool