Template Variables

This page provides a complete reference for all variables available in StaticForge templates. Template variables are the data points that Twig templates use to render content, including page metadata, site configuration, navigation menus, and feature-generated data.

For information about template structure and inheritance, see Template Inheritance. For details about the TemplateRenderer service and template resolution logic, see Template Architecture.

---

Variable Sources

StaticForge aggregates template variables from multiple sources during the rendering pipeline. The TemplateVariableBuilder service collects data from:

1. Content metadata: Extracted from frontmatter during file discovery
2. Container variables: Global configuration loaded from .env and siteconfig.yaml
3. Feature data: Structures built by features during event lifecycle
4. Computed values: System-generated data like URLs and cache busters

Diagram: Template Variable Aggregation Pipeline

Sources:

• content/development/templates.md74-91
• templates/staticforce/base.html.twig8-37

---

Core Variables

Core variables are available in all templates and contain fundamental page and site information.

Content Variables

Variable	Type	Description	Example
content	string	Rendered HTML content of the page	{{ content|raw }}
title	string	Page title from frontmatter	{{ title }}
description	string	Page meta description	{{ description }}
source_file	string	Relative path to source content file	guide/index.md

Usage in templates:

Sources:

• templates/staticforce/base.html.twig44-46
• templates/staticforce/base.html.twig98-100
• templates/staticforce/_chapter_nav.html.twig13

Site Variables

Variable	Type	Description	Configuration Source
site_name	string	Site name	siteconfig.yaml > site.name
site_tagline	string	Site tagline	siteconfig.yaml > site.tagline
site_base_url	string	Base URL with trailing slash	.env > SITE_BASE_URL

Usage in templates:

Critical: Always use site_base_url for asset paths to ensure correct URL resolution across different page depths.

Sources:

• templates/staticforce/base.html.twig44
• templates/staticforce/base.html.twig62
• templates/staticforce/_footer.html.twig33
• siteconfig.yaml5-8
• content/development/templates.md82-83

Metadata Variables

Additional frontmatter fields are passed through to templates as top-level variables:

Variable	Type	Description
tags	array/string	Content tags
category	string	Content category
date	string	Publication date
hero	string	Hero image path
template	string	Template name
Custom fields	mixed	Any additional frontmatter

Conditional rendering with metadata:

Sources:

• templates/staticforce/base.html.twig48-56
• templates/staticforce/docs.html.twig32-42

---

Menu Variables

StaticForge supports two independent menu systems: static named menus and numbered content-based menus.

Diagram: Menu Variable Namespace

Sources:

• content/guide/site-config.md92-108
• siteconfig.yaml16-22

Named Menus (Static)

Named menus are defined in siteconfig.yaml and accessible as menu_{name}.

Configuration:

Template access:

HTML output structure:

Sources:

• templates/staticforce/base.html.twig73-77
• templates/staticforce/_footer.html.twig17-30
• siteconfig.yaml16-22
• content/guide/site-config.md41-91

Numbered Menus (Content-Based)

Numbered menus are generated from content files with menu: X.Y frontmatter notation.

Variable	Menu Number	Usage
menu1	1	Primary navigation
menu2	2	Documentation sections
menu3	3	Feature pages
menu4	4	Development guides

Content frontmatter:

Template access:

Position notation:

• 1.0 - First item in menu 1
• 1.5 - Between 1.0 and 2.0
• 1.1.1 - First child of item 1.1
• 2.3 - Third item in menu 2

Sources:

• templates/staticforce/docs.html.twig48-61
• templates/staticforce/base.html.twig92-94
• content/development/templates.md89

Raw Menu Data

For advanced use cases, access structured menu data directly:

Sources:

• templates/staticforce/category.html.twig34-68

---

Feature Variables

Features expose data through the features namespace. Each feature has its own sub-namespace containing generated data structures.

Diagram: Feature Variable Structure

Sources:

• content/development/templates.md86-91
• templates/staticforce/docs.html.twig17

MenuBuilder Feature

Variable	Type	Description
features.MenuBuilder.files[N]	array	Structured menu data for menu N
features.MenuBuilder.html[N]	string	Pre-rendered HTML for menu N

Accessing menu data:

Sources:

• templates/staticforce/category.html.twig34
• content/development/templates.md89

ChapterNav Feature

Sequential navigation for documentation pages.

Variable	Type	Description
features.ChapterNav.pages[source_file]	array	Navigation data keyed by source file

Structure:

Template usage:

Sources:

• templates/staticforce/_chapter_nav.html.twig17-21
• templates/staticforce/docs.html.twig76

Tags Feature

Tag cloud and tag list generation.

Variable	Type	Description
features.Tags.cloud	string	HTML tag cloud
features.Tags.list	array	All tags with counts

Template usage:

Sources:

• content/development/templates.md90

Table of Contents (TOC)

Variable	Type	Description
toc	string	Generated table of contents HTML

Template usage:

Sources:

• templates/staticforce/docs.html.twig64-84

Category Variables

Variable	Type	Description
category_files	array	Files in the current category

File structure:

Template usage:

Sources:

• templates/staticforce/category.html.twig78-96

---

Asset Variables

Asset variables are managed by the AssetManager and automatically injected if not explicitly rendered.

Variable	Type	Description	Injection Point
styles	string	<link> tags for CSS	Before </head>
head_scripts	string	<script> tags for head	Before </head>
scripts	string	<script> tags for footer	Before </body>

Recommended placement:

Automatic injection: If these variables are not rendered in the template, TemplateRenderer automatically injects them before the closing </head> and </body> tags.

Sources:

• content/development/templates.md119-154
• templates/staticforce/base.html.twig62-63

---

Computed Variables

System-generated variables calculated during the build process.

Variable	Type	Description
cache_buster	string	Unique build identifier for cache invalidation
url	string	Absolute URL of current page

Usage:

Sources:

• templates/staticforce/base.html.twig62

---

Variable Access Patterns

Diagram: Variable Resolution Flow

Sources:

• content/development/architecture.md156-172

Checking Variable Existence

Always check for variable existence before use:

Sources:

• templates/staticforce/base.html.twig45-47
• templates/staticforce/_chapter_nav.html.twig17

Iterating Collections

Sources:

• templates/staticforce/category.html.twig36-66

Rendering Raw HTML

Use the raw filter for HTML content to prevent escaping:

Warning: Only use raw for trusted content. Never use it for user input.

Sources:

• templates/staticforce/base.html.twig99
• templates/staticforce/base.html.twig75

---

Form Variables

Forms feature provides variables for embedded form rendering.

Variable	Type	Description
endpoint	string	Form submission URL
fields	array	Field definitions
success_message	string	Success message text
error_message	string	Error message text
submit_text	string	Submit button text
challenge_url	string	Altcha spam protection URL

Configuration:

Template usage:

Sources:

• templates/staticforce/_form.html.twig7-20
• templates/staticforce/contact_us.html.twig17-33
• siteconfig.yaml31-59

---

Custom Feature Variables

Custom features can expose data through the features namespace:

In feature class:

In template:

Sources:

• content/development/architecture.md219-231
• content/development/features.md96-123

---

Variable Namespace Summary

Namespace	Purpose	Source
Top-level	Core page variables	Frontmatter, container
site_*	Site configuration	siteconfig.yaml, .env
menu_*	Named static menus	siteconfig.yaml
menu1..4	Numbered content menus	Frontmatter menu: X.Y
features.*	Feature-generated data	Feature event listeners
styles, scripts, etc.	Asset injection	AssetManager

Sources:

• templates/staticforce/base.html.twig8-37
• content/development/templates.md74-91