Template Architecture

Purpose and Scope

This document explains StaticForge's template architecture, including the directory structure for template storage, the three-tier template resolution algorithm, and the TemplateRenderer service that orchestrates Twig-based rendering. This page focuses on the structural and algorithmic aspects of template selection and application.

For information about template inheritance patterns and available Twig blocks, see Template Inheritance. For a complete reference of template variables, see Template Variables. For asset injection mechanisms, see Asset Management.

---

Template Directory Structure

StaticForge organizes templates in a hierarchical directory structure that supports multiple template themes. Templates are stored in the templates/ directory, with each theme in its own subdirectory.

templates/
├── staticforce/ # Active template theme
│ ├── base.html.twig # Master layout
│ ├── docs.html.twig # Documentation layout
│ ├── index.html.twig # Landing page layout
│ ├── standard_page.html.twig # Single-column layout
│ ├── category.html.twig # Category index layout
│ ├── _footer.html.twig # Footer partial
│ ├── _chapter_nav.html.twig # Navigation partial
│ ├── _form.html.twig # Form partial
│ └── contact_us.html.twig # Contact form template
└── [custom-theme]/ # Additional themes

The active template theme is determined by configuration resolution:

Priority	Source	Configuration Key	Example Value
1 (Highest)	siteconfig.yaml	site.template	staticforce
2	.env file	TEMPLATE	staticforce
3 (Lowest)	Hardcoded default	N/A	staticforce

The template directory path is stored in the Container as TEMPLATE_DIR and points to the absolute path of the templates/ directory. The active template name is stored as TEMPLATE.

Sources: src/Services/TemplateRenderer.php36-40 templates/staticforce/base.html.twig1-124

---

Template Resolution Algorithm

StaticForge employs a three-tier template resolution system that allows per-file, per-category, and system-wide template selection. The resolution occurs during the RENDER event when content files are processed.

Resolution Flow Diagram

Sources: src/Services/TemplateRenderer.php42-71

Resolution Priority Table

Priority	Source	Example	Container Storage
1 (Highest)	Frontmatter template field	template: docs → docs.html.twig	N/A (per-file metadata)
2 (Medium)	Category template mapping	category: blog → category maps to blog-post.html.twig	category_templates array
3 (Lowest)	Default template	No template specified → base.html.twig	Hardcoded in BaseRendererFeature

Frontmatter-Based Resolution

Content files can explicitly specify their template in frontmatter:

The TemplateRenderer checks for this field first: src/Services/TemplateRenderer.php46-48

Category-Based Resolution

When no explicit template is specified, the system checks if the content has a category field and whether that category has a template mapping:

The category name is slugified (lowercase, spaces/underscores to hyphens) and looked up in the category_templates Container variable: src/Services/TemplateRenderer.php49-67

Default Fallback

If neither frontmatter nor category provides a template, the system uses base as the template name. The default is defined in BaseRendererFeature: src/Core/BaseRendererFeature.php17

Sources: src/Services/TemplateRenderer.php42-71 src/Core/BaseRendererFeature.php33-39

---

TemplateRenderer Service

The TemplateRenderer service is the core rendering engine that applies Twig templates to processed content. It is instantiated by renderer features (MarkdownRenderer, HtmlRenderer) and manages the complete template rendering lifecycle.

Service Architecture Diagram

Sources: src/Services/TemplateRenderer.php14-25 src/Features/MarkdownRenderer/Feature.php50-62 src/Features/HtmlRenderer/Feature.php47-53

Service Dependencies

The TemplateRenderer constructor accepts three dependencies:

Parameter	Type	Required	Purpose
$variableBuilder	TemplateVariableBuilder	Yes	Assembles template context from multiple sources
$logger	Log	Yes	Logs template selection and rendering errors
$assetManager	AssetManager	No	Provides CSS/JS assets for auto-injection

Sources: src/Services/TemplateRenderer.php20-25

Primary Rendering Method

The render() method is the main entry point for template application:

Rendering Pipeline:

1. Template Resolution - Determines which template file to use via the three-tier algorithm
2. Twig Environment Setup - Creates FilesystemLoader and TwigEnvironment with security settings
3. Variable Building - Delegates to TemplateVariableBuilder to assemble template context
4. Template Rendering - Calls $twig->render() with template path and variables
5. Asset Injection - Optionally auto-injects CSS/JS if AssetManager is available and assets weren't rendered
6. Error Handling - Falls back to basic template if rendering fails

Sources: src/Services/TemplateRenderer.php32-104

Partial Template Rendering

The renderTemplate() method provides direct template rendering for features that need to render specific templates (e.g., shortcodes, forms):

This method bypasses the resolution algorithm and directly renders the specified template. It's used by features like Forms and Shortcodes to render component templates.

Sources: src/Services/TemplateRenderer.php115-148

---

Twig Environment Configuration

The TemplateRenderer configures Twig with specific security and performance settings for static site generation.

Configuration Table

Setting	Value	Purpose
debug	true	Enable debug mode for template development
strict_variables	false	Allow undefined variables without errors (fails gracefully)
autoescape	'html'	Enable automatic HTML escaping for XSS protection
cache	false	Disable template caching for development

Sources: src/Services/TemplateRenderer.php79-84

Filesystem Loader Configuration

The FilesystemLoader is configured with two namespace paths:

Path Resolution Order:

1. Active template directory (templates/staticforce/) - Templates in the active theme are searched first
2. Root templates directory (templates/) - Fallback for shared templates not in the active theme

This allows templates to reference partials using both absolute paths (staticforce/_footer.html.twig) and relative paths within the active theme (_footer.html.twig).

Sources: src/Services/TemplateRenderer.php76-78 src/Services/TemplateRenderer.php125-130

---

Integration with Renderer Features

The TemplateRenderer is instantiated and used by content renderer features during the RENDER event. Both MarkdownRenderer and HtmlRenderer follow the same integration pattern.

Renderer Feature Integration Diagram

Sources: src/Features/MarkdownRenderer/Feature.php80-83 src/Features/HtmlRenderer/Feature.php71-74

BaseRendererFeature Integration

Both renderer features extend BaseRendererFeature, which provides common metadata handling:

This ensures that all content files have a default template value of 'base' if no template is specified in frontmatter or category mappings.

Sources: src/Core/BaseRendererFeature.php33-39

Feature Instantiation Pattern

Renderer features instantiate TemplateRenderer during their register() method:

This pattern ensures each renderer feature has its own TemplateRenderer instance while sharing the same AssetManager (if available) for consistent asset injection.

Sources: src/Features/MarkdownRenderer/Feature.php50-62 src/Features/HtmlRenderer/Feature.php40-53

---

Fallback Rendering Mechanism

The TemplateRenderer includes a fallback mechanism that activates when Twig rendering fails (e.g., missing template file, syntax error):

The fallback template is a minimal HTML5 structure with placeholders for site name, page title, content, and metadata: src/Services/TemplateRenderer.php155-213

This ensures the build process never completely fails due to template errors, though the output will lack the full template features.

Sources: src/Services/TemplateRenderer.php98-103 src/Services/TemplateRenderer.php155-213

---

Template Name Slugification

When resolving category-based templates, the system slugifies category names to match filename conventions:

Examples:

Category Metadata	Slugified Name	Template Lookup
blog	blog	category_templates['blog']
Tech Blog	tech-blog	category_templates['tech-blog']
user_guides	user-guides	category_templates['user-guides']

This ensures consistent category template mapping regardless of how categories are named in content frontmatter.

Sources: src/Services/TemplateRenderer.php273-277