Module

rendering.template_functions.icons

Template functions for rendering SVG icons.

Provides optimized icon rendering functions for use in Jinja2 templates. Icons are pre-loaded at registration time and rendered output is cached by (name, size, css_class, aria_label) to minimize per-render overhead.

Performance:

  • All icons pre-loaded at template engine initialization (~86 icons, ~50KB)
  • Rendered SVG cached by parameters (typical hit rate: >95%)
  • Regex processing only on cache miss
  • Zero file I/O during template rendering
View source
8 Functions

Functions

_get_icons_directory
Get the icons directory from the default theme.
0 Path 
def _get_icons_directory() -> Path

Get the icons directory from the default theme.

Returns

Path

_preload_all_icons
Pre-load all icons into memory at startup. Called once during template engine initialization. Load…
0 None 
def _preload_all_icons() -> None

Pre-load all icons into memory at startup.

Called once during template engine initialization. Loads all SVG files from the icons directory into the _preloaded_icons cache.

_escape_attr
Escape HTML attribute value.
1 str 
def _escape_attr(value: str) -> str

Escape HTML attribute value.

Parameters 1

Name Type Default Description
value str —

Returns

str

_render_icon_cached
Render an icon with LRU caching for repeated calls. The cache key is (name, size, css_class, aria_…
4 str 
def _render_icon_cached(name: str, size: int, css_class: str, aria_label: str) -> str

Render an icon with LRU caching for repeated calls.

The cache key is (name, size, css_class, aria_label). This captures the vast majority of repeated icon renders (e.g., navigation icons appear on every page with the same parameters).

Parameters 4

Name Type Default Description
name str —

Icon name (already mapped through ICON_MAP)
size int —

Icon size in pixels
css_class str —

Additional CSS classes
aria_label str —

Accessibility label

Returns

str —

Rendered SVG HTML string, or empty string if icon not found

icon
Render an SVG icon for use in templates. Uses pre-loaded icons and LRU caching for optimal perform…
4 Markup 
def icon(name: str, size: int = 24, css_class: str = '', aria_label: str = '') -> Markup

Render an SVG icon for use in templates.

Uses pre-loaded icons and LRU caching for optimal performance. Icons are loaded once at startup and rendered output is cached by (name, size, css_class, aria_label) to minimize repeated work.

Icon name mapping priority:

  1. theme.yaml aliases (if theme config available)
  2. ICON_MAP (fallback for backwards compatibility)

Parameters 4

Name Type Default Description
name str —

Icon name (e.g., "search", "menu", "close", "arrow-up")
size int 24

Icon size in pixels (default: 24)
css_class str ''

Additional CSS classes
aria_label str ''

Accessibility label (if empty, uses aria-hidden)

Returns

Markup —

Markup object containing inline SVG HTML, or empty Markup if icon not found

register
Register icon template functions and pre-load all icons. Pre-loads all SVG icons into memory at re…
2 None 
def register(env: Environment, site: Site) -> None

Register icon template functions and pre-load all icons.

Pre-loads all SVG icons into memory at registration time for optimal render performance. Icons are typically ~50KB total.

Parameters 2

Name Type Default Description
env Environment —

Jinja2 environment
site Site —

Site instance (stored for theme config access)
get_icon_cache_stats
Get icon cache statistics for debugging/profiling.
0 dict[str, int] 
def get_icon_cache_stats() -> dict[str, int]

Get icon cache statistics for debugging/profiling.

Returns

dict[str, int] —

Dictionary with cache hit/miss information

clear_icon_cache
Clear the icon render cache. Useful for testing or when icons are modified during development.
0 None 
def clear_icon_cache() -> None

Clear the icon render cache.

Useful for testing or when icons are modified during development.