Module

content.versioning.resolver

Version-aware content path resolution.

This module provides the VersionResolver class that handles versioned content path resolution, shared content injection, and cross-version linking.

Key Concepts:

  • Source paths: Physical location (e.g.,_versions/v2/docs/guide.md)
  • Logical paths: Version-agnostic path (e.g.,docs/guide.md)
  • Output paths: Build output (e.g.,public/docs/v2/guide/index.html)
  • Shared content: Content in_shared/is included in all versions

Features:

  • Determine which version a content path belongs to
  • Resolve shared content paths for each version
  • Compute output paths with version prefixes
  • Handle cross-version content linking ([[v2:path/to/page]]syntax)
  • Strip/add version prefixes based on URL strategy

Architecture:

VersionResolver is used during discovery to assign version information to pages and during URL generation to compute version-aware paths. It integrates with Bengal's URLStrategy for consistent URL handling.

Related:

  • bengal/core/version.py: Version and VersionConfig models
  • bengal/content/discovery/content_discovery.py: Content discovery
  • bengal/content/versioning/git_adapter.py: Git-based version discovery
  • bengal/utils/url_strategy.py: URL generation
1Class

Classes

VersionResolver 12 ▼
Resolves versioned content paths and manages shared content. This class handles the mapping betwee…

Resolves versioned content paths and manages shared content.

This class handles the mapping between source paths, logical paths, and output paths for versioned documentation. It also manages shared content that appears in all versions.

Responsibilities:

  • Determine which version a content path belongs to
  • Resolve shared content paths for each version
  • Compute output paths with version prefixes
  • Handle cross-version content linking

Attributes

Name Type Description
version_config —

Site versioning configuration
root_path —

Site root directory
enabled —

Whether versioning is enabled (read-only property)

Methods

enabled 0 bool ▼
Check if versioning is enabled.
property
def enabled(self) -> bool
Returns
bool
get_version_for_path 1 Version | None ▼
Determine which version a content path belongs to. **Handles:** - _versions//*…
def get_version_for_path(self, content_path: Path | str) -> Version | None

Determine which version a content path belongs to.

Handles:

  • _versions//* paths → maps to specific version
  • Versioned section paths → maps to latest version
  • Non-versioned paths → returns None
Parameters
Name Type Description
content_path —

Path to content file (relative or absolute)
Returns
Version | None Version object or None if not versioned
get_logical_path 1 Path ▼
Get the logical path for a versioned content file. Strips version-specific pre…
def get_logical_path(self, content_path: Path | str) -> Path

Get the logical path for a versioned content file.

Strips version-specific prefixes to get the canonical path.

Parameters
Name Type Description
content_path —

Source content path
Returns
Path Logical path without version prefix
get_shared_content_paths 0 list[Path] ▼
Get paths to shared content directories. Shared content is included in all ver…
def get_shared_content_paths(self) -> list[Path]

Get paths to shared content directories.

Shared content is included in all versions (e.g., common images, reusable snippets, shared partials).

Returns
list[Path] List of absolute paths to shared content directories
should_include_shared_content 1 bool ▼
Check if shared content should be included for a version. By default, shared c…
def should_include_shared_content(self, version: Version) -> bool

Check if shared content should be included for a version.

By default, shared content is included in all versions. Can be disabled per-version via configuration.

Parameters
Name Type Description
version —

Version to check
Returns
bool True if shared content should be included
resolve_cross_version_link 2 str | None ▼
Resolve a cross-version link reference. Handles links like [[v2:path/to/page]]…
def resolve_cross_version_link(self, link_target: str, current_version: Version | None) -> str | None

Resolve a cross-version link reference.

Handles links like [[v2:path/to/page]] or [[latest:path/to/page]].

Parameters
Name Type Description
link_target —

Link target with optional version prefix
current_version —

Current page's version context
Returns
str | None Resolved URL path or None if not a version link
assign_version_to_page 2 ▼
Assign version information to a page based on its source path. Updates page.co…
def assign_version_to_page(self, page: Page, source_path: Path) -> None

Assign version information to a page based on its source path.

Updates page.core.version if the page belongs to a versioned section.

Parameters
Name Type Description
page —

Page to update
source_path —

Source content path
get_version_url_prefix 1 str ▼
Get the URL prefix for a version.
def get_version_url_prefix(self, version: Version | None) -> str
Parameters
Name Type Description
version —

Version object (None for unversioned content)
Returns
str URL prefix string (empty for latest, "/v2" for v2, etc.)
Internal Methods 1 ▼
__init__ 2 ▼
Initialize the version resolver.
def __init__(self, version_config: VersionConfig, root_path: Path) -> None
Parameters
Name Type Description
version_config —

Site versioning configuration
root_path —

Site root directory