Module

rendering.template_context

Template context wrappers for ergonomic URL handling.

Wraps Page and Section objects so that .url automatically includes baseurl in templates, making it impossible to forget baseurl in href/src attributes. Provides transparent delegation to wrapped objects while adding baseurl handling.

Key Concepts:

  • Auto-baseurl: Automatically applies baseurl to .url property
  • Transparent delegation: All other properties delegate to wrapped object
  • Multiple baseurl formats: Supports path, absolute, file, and S3 URLs
  • Template ergonomics: Simplifies template code by removing baseurl handling

Related Modules:

  • bengal.rendering.template_engine: Template engine that uses wrappers
  • bengal.core.page: Page objects being wrapped
  • bengal.core.section: Section objects being wrapped

See Also:

  • bengal/rendering/template_context.py: TemplatePageWrapper for page wrapper
  • bengal/rendering/template_context.py: TemplateSectionWrapper for section wrapper
View source
3 Classes 1 Function

Classes

TemplatePageWrapper
Wraps Page objects to auto-apply baseurl to .url in templates. Provides transparent wrapper that a…
6

Wraps Page objects to auto-apply baseurl to .url in templates.

Provides transparent wrapper that automatically applies baseurl to page URLs, making templates ergonomic. All other page properties delegate to the wrapped page object, maintaining full compatibility.

Creation:

Direct instantiation: TemplatePageWrapper(page, baseurl="")
  • Created by TemplateEngine for template context
  • Requires Page instance and optional baseurl

Attributes

Name Type Description
_page —

Wrapped Page object
_baseurl —

Base URL from site config (can be empty, path-only, or absolute)
Relationships —
  • Uses: Page for wrapped page object - Used by: TemplateEngine for template context - Used in: Templates via template context Baseurl Formats Supported: - Path-only:/bengal→/bengal/docs/page/- Absolute:https://example.com→https://example.com/docs/page/- File protocol:file:///path/to/site→file:///path/to/site/docs/page/- S3:s3://bucket/path→s3://bucket/path/docs/page/

Methods 3

url property
URL with baseurl applied (for templates). This is the property templates shoul…
str 
def url(self) -> str

URL with baseurl applied (for templates).

This is the property templates should use for href/src attributes. It automatically includes baseurl, so theme developers don't need to remember to use permalink or filters.

Returns

str

permalink property
Alias for url (for backward compatibility). Both url and permalink now return …
str 
def permalink(self) -> str

Alias for url (for backward compatibility).

Both url and permalink now return the same value (with baseurl). This maintains compatibility with existing templates that use permalink.

Returns

str

relative_url property
Relative URL without baseurl (for comparisons). Use this when you need the rel…
str 
def relative_url(self) -> str

Relative URL without baseurl (for comparisons).

Use this when you need the relative URL for comparisons or logic. For display URLs, use .url (which includes baseurl).

Returns

str

Internal Methods 3
__init__
Initialize wrapper.
2 None 
def __init__(self, page: Any, baseurl: str = '')

Initialize wrapper.

Parameters 2
page Any

Page object to wrap
baseurl str

Base URL from site config (can be empty, path-only, or absolute)
__getattr__
Delegate all other attributes to wrapped page. This makes the wrapper transpar…
1 Any 
def __getattr__(self, name: str) -> Any

Delegate all other attributes to wrapped page.

This makes the wrapper transparent - all page properties work as expected.

Parameters 1
name str
Returns

Any

__repr__
String representation for debugging.
0 str 
def __repr__(self) -> str

String representation for debugging.

Returns

str

TemplateSectionWrapper
Wraps Section objects to auto-apply baseurl to .url in templates. Provides transparent wrapper tha…
11

Wraps Section objects to auto-apply baseurl to .url in templates.

Provides transparent wrapper that automatically applies baseurl to section URLs, similar to TemplatePageWrapper. Also wraps pages and subsections when accessed to ensure consistent baseurl handling throughout the section hierarchy.

Creation:

Direct instantiation: TemplateSectionWrapper(section, baseurl="")
  • Created by TemplateEngine for template context
  • Requires Section instance and optional baseurl

Attributes

Name Type Description
_section —

Wrapped Section object
_baseurl —

Base URL from site config
Relationships —
  • Uses: Section for wrapped section object - Used by: TemplateEngine for template context - Used in: Templates via template context - Wraps: Pages and subsections when accessed

Methods 8

url property
URL with baseurl applied (for templates).
str 
def url(self) -> str

URL with baseurl applied (for templates).

Returns

str

permalink property
Alias for url (for backward compatibility).
str 
def permalink(self) -> str

Alias for url (for backward compatibility).

Returns

str

relative_url property
Relative URL without baseurl (for comparisons).
str 
def relative_url(self) -> str

Relative URL without baseurl (for comparisons).

Returns

str

pages property
Return wrapped pages.
list[TemplatePageWrapper] 
def pages(self) -> list[TemplatePageWrapper]

Return wrapped pages.

Returns

list[TemplatePageWrapper]

subsections property
Return wrapped subsections.
list[TemplateSectio… 
def subsections(self) -> list[TemplateSectionWrapper]

Return wrapped subsections.

Returns

list[TemplateSectionWrapper]

sorted_pages property
Return wrapped sorted pages.
list[TemplatePageWrapper] 
def sorted_pages(self) -> list[TemplatePageWrapper]

Return wrapped sorted pages.

Returns

list[TemplatePageWrapper]

sorted_subsections property
Return wrapped sorted subsections.
list[TemplateSectio… 
def sorted_subsections(self) -> list[TemplateSectionWrapper]

Return wrapped sorted subsections.

Returns

list[TemplateSectionWrapper]

index_page property
Return wrapped index page.
Any 
def index_page(self) -> Any

Return wrapped index page.

Returns

Any

Internal Methods 3
__init__
Initialize wrapper.
2 None 
def __init__(self, section: Any, baseurl: str = '')

Initialize wrapper.

Parameters 2
section Any

Section object to wrap
baseurl str

Base URL from site config
__getattr__
Delegate all other attributes to wrapped section.
1 Any 
def __getattr__(self, name: str) -> Any

Delegate all other attributes to wrapped section.

Parameters 1
name str
Returns

Any

__repr__
String representation for debugging.
0 str 
def __repr__(self) -> str

String representation for debugging.

Returns

str

TemplateSiteWrapper
Wraps Site object to auto-wrap pages/sections when accessed from templates. When templates access …
5

Wraps Site object to auto-wrap pages/sections when accessed from templates.

When templates access site.pages or site.sections, the pages/sections are automatically wrapped so they have .relative_url and .url includes baseurl.

Methods 3

pages property
Return wrapped pages.
list[TemplatePageWrapper] 
def pages(self) -> list[TemplatePageWrapper]

Return wrapped pages.

Returns

list[TemplatePageWrapper]

sections property
Return wrapped sections.
list[TemplateSectio… 
def sections(self) -> list[TemplateSectionWrapper]

Return wrapped sections.

Returns

list[TemplateSectionWrapper]

regular_pages property
Return wrapped regular pages.
list[TemplatePageWrapper] 
def regular_pages(self) -> list[TemplatePageWrapper]

Return wrapped regular pages.

Returns

list[TemplatePageWrapper]

Internal Methods 2
__init__
Initialize wrapper.
2 None 
def __init__(self, site: Any, baseurl: str = '')

Initialize wrapper.

Parameters 2
site Any

Site object to wrap
baseurl str

Base URL from site config
__getattr__
Delegate all other attributes to wrapped site.
1 Any 
def __getattr__(self, name: str) -> Any

Delegate all other attributes to wrapped site.

Parameters 1
name str
Returns

Any

Functions

wrap_for_template
Wrap Page or Section objects for template context. This function automatically detects the object …
2 Any 
def wrap_for_template(obj: Any, baseurl: str = '') -> Any

Wrap Page or Section objects for template context.

This function automatically detects the object type and wraps it appropriately. Other objects are returned unchanged.

Parameters 2

Name Type Default Description
obj Any —

Page, Section, SimpleNamespace (special pages), or other object
baseurl str ''

Base URL from site config

Returns

Any —

Wrapped object (if Page/Section/SimpleNamespace with url) or original object