Module

rendering.template_functions.changelog

Changelog view filters for templates.

Provides normalized ReleaseView dataclass andreleasesfilter to unify data-driven (changelog.yaml) and page-driven (individual markdown files) changelog modes.

Smart Version Detection:

The filter intelligently extracts version from multiple sources:

1. Explicit `version` field in frontmatter (highest priority)
2. Filename if versioned (e.g., `0.1.8.md` → "0.1.8")
3. Version pattern in title (e.g., "Bengal 0.1.8" → "0.1.8")
4. Full title as fallback

Supports semver (0.1.8, 1.0.0-beta) and date versioning (26.01).

Sorting:

Releases are sorted by **version** using semantic comparison, so
"0.1.10" correctly comes before "0.1.9". Same-version releases
fall back to date sorting.

Use `releases(false)` to preserve input order for custom sorting.

Example:

{# Standard - sorted by version, highest first #}
{% for rel in pages | releases %}
  <h2>{{ rel.version }}</h2>
{% end %}
1Class8Functions

Classes

ReleaseView 17 ▼
Normalized view of a changelog release for templates. Unifies data-driven (from changelog.yaml) an…

Normalized view of a changelog release for templates.

Unifies data-driven (from changelog.yaml) and page-driven (from markdown files) releases into a single consistent interface.

Attributes

Name Type Description
version str

Version string (e.g., "1.2.0")
name str

Release name/codename
date datetime | None

Release date (always datetime for reliable sorting, or None)
status str

Release status (stable, beta, rc, deprecated)
href str

URL to release page (if page-driven)
summary str

Brief release summary
added tuple[str, ...]

List of added features
changed tuple[str, ...]

List of changes
fixed tuple[str, ...]

List of bug fixes
deprecated tuple[str, ...]

List of deprecated features
removed tuple[str, ...]

List of removed features
security tuple[str, ...]

List of security fixes
breaking tuple[str, ...]

List of breaking changes
has_structured_changes bool

Whether release has categorized changes
change_types tuple[str, ...]

List of change type names present

Methods

from_data 1 ReleaseView ▼
Create a ReleaseView from a data-driven release dict. Typically from changelog…
classmethod
def from_data(cls, release: dict[str, Any]) -> ReleaseView

Create a ReleaseView from a data-driven release dict.

Typically from changelog.yaml with structure:

  • version: "1.2.0" 
    date: "2024-01-15"

    added: ["Feature 1", "Feature 2"]
Parameters
Name Type Description
release —

Release dict from data file
Returns
ReleaseView Normalized ReleaseView instance
from_page 1 ReleaseView ▼
Create a ReleaseView from a page-driven release. **Version extraction priority…
classmethod
def from_page(cls, page: Any) -> ReleaseView

Create a ReleaseView from a page-driven release.

Version extraction priority:

  1. Explicit metadata.version field
    1. Filename if it's a version (e.g., "0.1.8.md")
    2. Version extracted from title (e.g., "Bengal 0.1.8" → "0.1.8")
    3. Full title as fallback
Parameters
Name Type Description
page —

Page object representing a release
Returns
ReleaseView Normalized ReleaseView instance

Functions

_extract_version 1 str | None ▼
Extract a version string from text (title, filename, etc.). Recognizes: - Semv…
def _extract_version(text: str) -> str | None

Extract a version string from text (title, filename, etc.).

Recognizes:

  • Semver: "0.1.8", "v1.2.3", "1.0.0-beta"
  • Date versions: "26.01", "2026.01.12"
  • Prefixed: "Bengal 0.1.8" → "0.1.8"

Returns None if no version pattern found.

Parameters
Name Type Description
text str
Returns
str | None
_version_sort_key 1 tuple ▼
Parse version string into tuple for proper numeric sorting. **Handles:** - Sem…
def _version_sort_key(version: str) -> tuple

Parse version string into tuple for proper numeric sorting.

Handles:

  • Semantic versioning: "1.2.3", "0.1.10", "2.0.0-beta"
  • Date versioning: "26.01", "2026.01.12"
Parameters
Name Type Description
version str
Returns
tuple
_normalize_date 1 datetime | None ▼
Normalize a date value to datetime for reliable sorting. **Handles:** - dateti…
def _normalize_date(value: Any) -> datetime | None

Normalize a date value to datetime for reliable sorting.

Handles:

  • datetime objects (returned as-is)
  • date objects (converted to datetime at midnight)
  • ISO format strings (parsed)
  • None (returned as-is)
Parameters
Name Type Description
value Any
Returns
datetime | None
_to_tuple 1 tuple[str, ...] ▼
Convert a list/iterable to a tuple of strings, or empty tuple.
def _to_tuple(value: Any) -> tuple[str, ...]
Parameters
Name Type Description
value Any
Returns
tuple[str, ...]
_sort_releases 1 list[ReleaseView] ▼
Sort releases by version (highest first) using semantic comparison. Version is…
def _sort_releases(releases: list[ReleaseView]) -> list[ReleaseView]

Sort releases by version (highest first) using semantic comparison.

Version is the primary sort key because version IS the release identity. Date is secondary (for same-version edge cases).

Uses proper numeric comparison so "0.1.10" > "0.1.9" > "0.1.2". Stable versions sort before prereleases: "1.0.0" > "1.0.0-beta".

Sort order:

1. By version (highest first, semantic comparison)
2. For same version: by date (newest first)
Parameters
Name Type Description
releases list[ReleaseView]
Returns
list[ReleaseView]
releases_filter 2 list[ReleaseView] ▼
Convert releases to normalized ReleaseView objects, sorted by version. By defa…
def releases_filter(source: Any, sorted: bool = True) -> list[ReleaseView]

Convert releases to normalized ReleaseView objects, sorted by version.

By default, releases are sorted by version (highest first) using semantic comparison. This means "0.1.10" correctly comes before "0.1.9".

Version is extracted intelligently:

  1. Explicitversionfield in metadata
    1. Filename if versioned (e.g.,0.1.8.md)
    2. Version pattern in title (e.g., "Bengal 0.1.8")
    3. Full title as fallback
Parameters
Name Type Description
source Any

List of release dicts (from YAML) or Page objects (from section)
sorted bool

Sort by version (default: True). Set to False to preserve input order for custom sorting.

Default:True
Returns
list[ReleaseView]
release_view_filter 1 ReleaseView | None ▼
Convert a single release item to a ReleaseView.
def release_view_filter(item: Any) -> ReleaseView | None
Parameters
Name Type Description
item Any

Release dict or Page object
Returns
ReleaseView | None
register 2 None ▼
Register changelog view filters with template environment.
def register(env: TemplateEnvironment, site: SiteLike) -> None
Parameters
Name Type Description
env TemplateEnvironment
site SiteLike