VOOZH about

URL: https://deepwiki.com/calevans/staticforge/6.2-template-inheritance

⇱ Template Inheritance | calevans/staticforge | DeepWiki

Loading...
Loading...
Last indexed: 11 February 2026 (5f6a2a)
Menu

Template Inheritance

This document explains StaticForge's Twig-based template inheritance system: how master layouts define reusable structure through blocks, and how child templates extend and override those blocks to create different page layouts. For information about how templates are selected and resolved, see Template Architecture. For details on what variables are available in templates, see Template Variables.

Purpose and Scope

Template inheritance in StaticForge uses Twig's {% extends %} and {% block %} directives to create a hierarchy of templates where child templates inherit structure from parent templates and selectively override specific sections. This approach eliminates HTML duplication, enforces consistent site structure, and allows multiple page layouts to share common elements like navigation and footers while customizing content areas.

The core pattern involves:

  • A master layout (base.html.twig) defining the complete HTML document structure
  • Child templates extending the master and overriding specific blocks
  • Partials included by any template for reusable components

Twig Template Inheritance Model

The Extends Directive

Child templates declare their parent using {% extends %}:



templates/staticforce/docs.html.twig23


When Twig processes this template, it:


    

  1. Loads the parent template (base.html.twig)
    2. 

  2. Identifies all {% block %} definitions in both templates
    3. 

  3. Replaces parent blocks with child blocks where overrides exist
    4. 

  4. Renders the merged template
    5. 



The Block System


Blocks are named sections in templates that can be overridden:


Parent template defines blocks:




Child template overrides blocks:




Blocks can be replaced entirely (child provides new content) or extended (child adds to parent content using {{ parent() }}).


Sources: content/development/templates.md18-72 templates/staticforce/docs.html.twig1-88




Master Layout Architecture


The base.html.twig Structure


The base.html.twig template serves as the foundation for all page types. It defines the complete HTML document structure and declares extension points through blocks.


Template Inheritance Hierarchy Diagram:




Sources: templates/staticforce/base.html.twig1-124 templates/staticforce/docs.html.twig23 templates/staticforce/index.html.twig17




Block Reference


Complete Block Structure


The base.html.twig master layout defines seven extension points:


Base Layout Block Architecture:




Sources: templates/staticforce/base.html.twig39-123




Block Definitions Table























































Block NameLocationDefault ContentTypical Override Purpose
title<head>{{ title }} | {{ site_name }}`Customize page title format
extra_head<head>EmptyAdd page-specific CSS, meta tags
search_bar<nav>Search input HTMLHide search (landing pages)
body<body>Sidebar + content containerComplete layout override
content<main>{{ content|raw }}Wrap content with additional HTML
search_scriptsBottom of <body>Search initialization JSDisable search functionality
scriptsBottom of <body>EmptyAdd page-specific JavaScript


Sources: templates/staticforce/base.html.twig44-121




Block 1: title


Purpose: Controls the <title> tag content in the document head.


Default Implementation:




templates/staticforce/base.html.twig44


Override Pattern:




templates/staticforce/standard_page.html.twig1-11 (reference pattern from content/development/templates.md)


Data Flow: Receives title and site_name from TemplateVariableBuilder, formats for SEO and browser tabs.




Block 2: extra_head


Purpose: Injection point for page-specific stylesheets, meta tags, and head scripts.


Default Implementation: Empty block.


Usage in docs.html.twig:




templates/staticforce/docs.html.twig25-29


Usage in index.html.twig:




templates/staticforce/index.html.twig22-24


Pattern: Always use {{ site_base_url }} for asset paths to ensure correct resolution regardless of page depth in directory structure.


Sources: templates/staticforce/docs.html.twig25-29 templates/staticforce/index.html.twig22-24 templates/staticforce/standard_page.html.twig13-23




Block 3: search_bar


Purpose: Controls the search input interface in the navigation bar.


Default Implementation:




templates/staticforce/base.html.twig79-84


Empty Override (Landing Pages):




templates/staticforce/index.html.twig19


Rationale: Landing pages often have their own search implementation or no search at all. Emptying this block removes the navigation search widget.




Block 4: body


Purpose: Defines the entire main content area structure. This is the most commonly overridden block for creating different page layouts.


Default Implementation:




templates/staticforce/base.html.twig89-103


This default provides a two-column layout (sidebar + content).


Sources: templates/staticforce/base.html.twig89-103




Block 5: content


Purpose: Nested inside body block, contains the actual page content. Override to wrap content with additional markup.


Default Implementation:




templates/staticforce/base.html.twig98-100


Override in docs.html.twig:




templates/staticforce/docs.html.twig71-73


Pattern: When overriding body entirely, child templates often redefine content as well to maintain granular control.




Block 6: search_scripts


Purpose: JavaScript initialization for search functionality.


Default Implementation:




templates/staticforce/base.html.twig108-120


Empty Override:




templates/staticforce/index.html.twig20


Dependency: Requires Search feature to be enabled and search.json to exist.




Block 7: scripts


Purpose: Generic injection point for page-specific JavaScript at the end of <body>.


Default Implementation: Empty block.


templates/staticforce/base.html.twig121


Usage Pattern:




Sources: templates/staticforce/base.html.twig39-123




Child Template Patterns


Pattern 1: Layout Override (docs.html.twig)


The documentation template completely overrides the body block to create a three-column layout (sidebar, content, table of contents).


Three-Column Layout Structure:




Implementation:




templates/staticforce/docs.html.twig31-87


Key Differences from Base:


    

  • Adds optional hero image section
    • 

  • Sidebar displays multiple menus (menu2, menu3, menu4) instead of menu1
    • 

  • Adds right-side table of contents column
    • 

  • Includes _chapter_nav.html.twig partial for prev/next navigation
    • 

  • Redefines nested content block to maintain extension point
    • 



Sources: templates/staticforce/docs.html.twig31-87




Pattern 2: Minimal Override (index.html.twig)


The landing page removes unwanted features and uses full-width layout.


Block Override Strategy:




templates/staticforce/index.html.twig17-28


Strategy:


    

  • Empty blocks: search_bar and search_scripts blocks emptied to disable search
    • 

  • Custom CSS: Adds home.css via extra_head
    • 

  • Complete body override: Removes all layout structure, renders raw content
    • 



Use Case: Homepage content file (content/index.md) provides its own HTML structure using inline HTML in Markdown, styled by home.css.


Sources: templates/staticforce/index.html.twig1-29




Pattern 3: Centered Content (standard_page.html.twig)


Simple single-column layout for general content pages.


Implementation:




templates/staticforce/standard_page.html.twig1-42


Features:


    

  • Optional hero image (same pattern as docs.html.twig)
    • 

  • Single centered content column with max-width constraint
    • 

  • Inline CSS for layout (could be extracted to external stylesheet)
    • 

  • No sidebars, no TOC
    • 



Sources: templates/staticforce/standard_page.html.twig1-42




Partial Includes


Include vs. Extends


Templates use two mechanisms for composition:

























MechanismSyntaxPurposeExample
Extends{% extends 'base.html.twig' %}Inheritance hierarchyChild template inherits parent structure
Include{% include '_partial.html.twig' %}Component insertionFooter, forms, navigation components


Convention: Partial templates (meant to be included, not extended) use underscore prefix: _footer.html.twig, _chapter_nav.html.twig, _form.html.twig.




Common Partials


Footer Partial:




templates/staticforce/base.html.twig105


Renders site footer with menu and copyright. Variables: menu_footer, site_name, site_tagline.


templates/staticforce/_footer.html.twig1-36


Chapter Navigation Partial:




templates/staticforce/docs.html.twig76


Renders prev/next links for sequential documentation pages. Requires ChapterNav feature.


templates/staticforce/_chapter_nav.html.twig1-23


Form Partial:




Variables: endpoint, fields, success_message, error_message, challenge_url.


templates/staticforce/_form.html.twig1-86


Sources: templates/staticforce/base.html.twig105 templates/staticforce/_footer.html.twig1-36 templates/staticforce/_chapter_nav.html.twig1-23 templates/staticforce/_form.html.twig1-86




Template Resolution and Inheritance


Resolution Process


When rendering a file, StaticForge determines which template to use via three-tier priority:


Template Resolution Flow:




Example Resolution:


Given file with template: docs:


    

  1. Resolved to: templates/staticforce/docs.html.twig
    2. 

  2. docs.html.twig contains: {% extends 'base.html.twig' %}
    3. 

  3. Base resolved to: templates/staticforce/base.html.twig
    4. 

  4. Twig merges blocks from both templates
    5. 

  5. Final HTML generated
    6. 



Sources: content/development/templates.md178-194




Block Override Best Practices


Rule 1: Preserve Extension Points


When overriding body block, consider whether to redefine the content sub-block:


Good (Maintains Extension Point):




Acceptable (Single-Purpose Template):




templates/staticforce/index.html.twig26-28


Rationale: Redefining content allows future templates to extend your template and override just the content area.




Rule 2: Always Use site_base_url for Assets


Correct:




Incorrect:




Reason: Files at different directory depths need absolute URLs. A file at /blog/post.html would incorrectly resolve css/style.css to /blog/css/style.css.


Sources: content/development/templates.md157-175




Rule 3: Empty vs. Override


Two ways to disable block content:


Empty (Remove Completely):




Replace (Provide Alternative):




Use empty blocks when feature should not appear. Use replacement when providing different implementation.




Variable Inheritance and Scope


Available in All Templates


All templates in the inheritance chain have access to the same variable context passed by TemplateRenderer:


Template Variable Data Flow:




Key Point: Variables are not inherited through the template chain; they're passed to the entire template tree at render time. Both parent and child templates see the same variable scope.


Sources: content/development/templates.md74-92




Creating Custom Inheritance Hierarchies


Multi-Level Inheritance


While uncommon, templates can extend non-base templates:






Inheritance Chain: blog_post.html.twig → article_base.html.twig → base.html.twig


Pattern: Useful for creating template families (articles, product pages, landing pages) that share specialized structure.




Summary


StaticForge's template inheritance system provides:





































ConceptImplementationPurpose
Master Layoutbase.html.twigDefines complete HTML structure and reusable blocks
Extension{% extends 'base.html.twig' %}Child inherits parent structure
Override{% block name %}...{% endblock %}Replace specific sections
Inclusion{% include '_partial.html.twig' %}Insert reusable components
Variable ScopeTemplateRenderer contextAll templates in chain access same variables


The seven blocks in base.html.twig (title, extra_head, search_bar, body, content, search_scripts, scripts) provide fine-grained control over page structure while maintaining DRY principles.


Child templates choose their override strategy based on layout requirements: minimal changes (empty blocks), moderate customization (extra_head + body), or complete restructuring (full body override with custom layout).


Sources: templates/staticforce/base.html.twig1-124 templates/staticforce/docs.html.twig1-88 templates/staticforce/index.html.twig1-29 templates/staticforce/standard_page.html.twig1-42 content/development/templates.md1-270
Refresh this wiki
On this page