VOOZH about

URL: https://deepwiki.com/calevans/staticforge/4.2-site-configuration-(siteconfig.yaml)

⇱ Site Configuration (siteconfig.yaml) | calevans/staticforge | DeepWiki

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

Site Configuration (siteconfig.yaml)

Purpose and Scope

This document describes the siteconfig.yaml configuration file, which provides version-controlled, non-sensitive site settings for StaticForge. Unlike .env which contains environment-specific credentials and URLs (see #4.1), siteconfig.yaml contains site metadata, menu definitions, feature configuration, and other structural settings that should be committed to version control and shared across environments.

For information about how configuration values are resolved when multiple sources define the same setting, see Configuration Resolution.

File Location and Optional Nature

The siteconfig.yaml file is located in the project root directory, alongside .env, content/, and templates/. The file is completely optional—StaticForge operates without it, falling back to defaults and environment variables.

project-root/
├── .env # Environment-specific settings
├── siteconfig.yaml # Site-wide configuration (this file)
├── content/ # Content files
├── templates/ # Twig templates
└── vendor/ # Dependencies

Sources: siteconfig.yaml.example1-10

Configuration Loading Process

Bootstrap Integration

The configuration file is loaded during application bootstrap, immediately after environment variables are processed but before features are initialized.

Loading Flow



Sources: content/development/bootstrap.md59-65 siteconfig.yaml.example1-10


Error Handling


    

  • Missing file: Bootstrap continues without error, features use defaults
    • 

  • Parse errors: Logged but do not halt site generation
    • 

  • Invalid structure: Individual features validate their own configuration sections
    • 



Sources: content/guide/site-config.md267-275




Configuration Structure Overview


The configuration file uses YAML syntax with top-level keys representing functional areas. Each section is independent and consumed by specific features or core components.


Top-Level Structure




Sources: siteconfig.yaml1-84 siteconfig.yaml.example11-150




Configuration Sections Reference


Site Information


Defines core site metadata accessible throughout templates and features.











































FieldTypeDescriptionTemplate Variable
namestringSite name{{ site_name }}
titlestringFull site title{{ site_title }}
descriptionstringSite description{{ site_description }}
taglinestringSite tagline/slogan{{ site_tagline }}
templatestringDefault template directory nameUsed for template resolution


Example Configuration:




Sources: siteconfig.yaml3-8 siteconfig.yaml.example11-17




Social Metadata


Default values for social media integration features like Open Graph and Twitter Cards.






















FieldTypeDescription
twitter_handlestringDefault Twitter username (with @)
default_imagestringDefault social sharing image path


Example Configuration:




Sources: siteconfig.yaml10-13 siteconfig.yaml.example18-23




Static Menu Definitions


Defines named menus that contain hardcoded links (not derived from content files). These are distinct from numbered menus (e.g., menu: 1.1 in frontmatter).


Menu System Architecture




Configuration Syntax:




Key Characteristics:


    

  • Menu names are arbitrary (e.g., top, footer, utility)
    • 

  • Items are key-value pairs: Display Text: /url
    • 

  • Order in YAML determines display order
    • 

  • Accessible in templates as {{ menu_{name} }}
    • 

  • External URLs are fully supported
    • 



Generated HTML Structure:




Sources: siteconfig.yaml15-22 content/guide/site-config.md41-91




Static vs. Numbered Menu Systems


StaticForge supports two independent menu systems that coexist without conflict.










































AspectStatic MenusNumbered Menus
Definitionsiteconfig.yaml under menu:Content frontmatter: menu: 1.5
Access Pattern{{ menu_top }}, {{ menu_footer }}{{ menu1 }}, {{ menu2 }}
OrderingYAML file orderNumeric position (1.0, 1.5, 2.0)
SourceHand-curatedAuto-discovered from content
Use CaseExternal links, static structureContent-driven navigation
FeatureMenuBuilder (static section)MenuBuilder (numbered section)


Sources: content/guide/site-config.md92-108




Chapter Navigation Configuration


Controls sequential navigation (previous/next links) for numbered menus.





































FieldTypeDefaultDescription
menusstring-Comma-separated menu numbers (e.g., "2,3")
prev_symbolstring←Symbol for previous link
next_symbolstring→Symbol for next link
separatorstring|Separator between navigation elements


Example Configuration:




Fallback Behavior: If not defined in siteconfig.yaml, ChapterNav feature checks environment variables: CHAPTER_NAV_MENUS, CHAPTER_NAV_PREV_SYMBOL, CHAPTER_NAV_NEXT_SYMBOL, CHAPTER_NAV_SEPARATOR.


Sources: siteconfig.yaml24-28 content/guide/site-config.md193-223




Forms Configuration


Defines embeddable forms accessible via {{ form('name') }} shortcode in content.


Form Structure:




Field Types Supported:


    

  • text - Single-line text input
    • 

  • email - Email address input
    • 

  • textarea - Multi-line text input
    • 



Sources: siteconfig.yaml30-59 siteconfig.yaml.example67-106




Calendars Configuration


Defines named calendars for the calendar shortcode [[calendar name="work"]].


Configuration Structure:




Calendar Event Files:


Events are stored as markdown files in content/calendars/{calendar_name}/:


content/calendars/
└── example_events/
 ├── team-meeting.md
 ├── project-deadline.md
 └── lunch-learn.md



Event Frontmatter:




Sources: siteconfig.yaml61-66 siteconfig.yaml.example135-149 content/calendars/example_events/team-meeting.md1-5




Disabled Features


List of feature names to exclude from loading. Both core and custom features can be disabled.




Effect:


    

  • Feature is not loaded by FeatureManager
    • 

  • Event listeners are not registered
    • 

  • Dependent features (using requireFeatures) may also be skipped
    • 



Sources: siteconfig.yaml68-70 content/guide/site-config.md110-124




Google Analytics Configuration


Controls Google Analytics feature activation. The tracking ID is specified in .env as GOOGLE_ANALYTICS_ID.




Sources: siteconfig.yaml72-75 siteconfig.yaml.example118-121




Search Configuration


Configures the search feature and search index generation.











































FieldTypeDefaultDescription
enabledbooleantrueEnable/disable search feature
enginestringminisearchSearch engine: minisearch or fuse
exclude_pathsarray[]URL paths to exclude from index
exclude_content_inarray[]Content directories to exclude
separatorstring|Separator between navigation elements


Example Configuration:




Search Engine Comparison:






















EngineStrengthsUse Case
minisearchFaster exact/prefix matchingLarge sites with precise search needs
fuseBetter fuzzy matching, typo toleranceSites requiring flexible search


Sources: siteconfig.yaml77-84 siteconfig.yaml.example49-65




S3 Media Offload Configuration


Configures AWS S3 or S3-compatible storage for static asset offloading.




Credential Sources:


    

  • Configuration keys: key, secret (not recommended)
    • 

  • Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
    • 

  • IAM roles (recommended for production)
    • 



Sources: siteconfig.yaml.example123-133




Accessing Configuration from Code


From Features


Features extending BaseFeature can access their configuration section using the getConfig() method.


Configuration Access Pattern:




Example Feature Code:




Configuration Section Naming: The configuration is accessed using the feature's class name. For a feature at src/Features/MyFeature/Feature.php, the configuration section is site_config['MyFeature'].


Sources: content/development/features.md96-123




From Container


Direct access to the full configuration array:




Sources: content/development/bootstrap.md59-65




From Templates


Site-level configuration values are exposed as template variables:




Variable Mapping:































Configuration PathTemplate Variable
site.name{{ site_name }}
site.tagline{{ site_tagline }}
site.description{{ site_description }}
menu.top{{ menu_top }}
menu.footer{{ menu_footer }}


Sources: content/guide/site-config.md66-77 content/development/templates.md78-91




Configuration Resolution Hierarchy


When multiple configuration sources define the same value, the resolution order is:


    

  1. CLI Options (highest priority)
    2. 

  2. siteconfig.yaml
    3. 

  3. .env file
    4. 

  4. Hardcoded defaults (lowest priority)
    5. 



Example: Template Selection




Sources: content/development/templates.md186-194 See also #4.3




Complete Example


A comprehensive siteconfig.yaml demonstrating all major sections:




Sources: siteconfig.yaml1-84 siteconfig.yaml.example1-150




Version Control Best Practices


DO commit to version control:


    

  • siteconfig.yaml - Contains no sensitive information
    • 

  • siteconfig.yaml.example - Template for new environments
    • 



DO NOT commit:


    

  • .env - Contains credentials and environment-specific URLs
    • 



Rationale: Configuration in siteconfig.yaml defines site structure and behavior that should be consistent across all environments. Environment-specific values (database URLs, API keys, deployment credentials) belong in .env.


Sources: content/guide/site-config.md368-372 siteconfig.yaml.example1-9




Troubleshooting


Configuration Not Loading


Symptoms: Features report missing configuration, default values used


Diagnosis:


    

  1. Verify file exists at project root: ls -la siteconfig.yaml
    2. 

  2. Check YAML syntax: php -r "yaml_parse_file('siteconfig.yaml');"
    3. 

  3. Review bootstrap logs for parse errors
    4. 

  4. Confirm Container variable: $container->getVariable('site_config')
    5. 



Sources: content/guide/site-config.md374-388




Menu Not Appearing in Templates


Symptoms: {{ menu_top }} renders empty or undefined


Diagnosis:


    

  1. Verify menu is defined in siteconfig.yaml under menu: section
    2. 

  2. Check menu name matches template variable (top: → {{ menu_top }})
    3. 

  3. Confirm MenuBuilder feature is not disabled
    4. 

  4. Review MenuBuilder priority in POST_GLOB event
    5. 

  5. Check browser HTML source for HTML comments (MenuBuilder may inject comments)
    6. 



Common Error: Confusing static menus (menu_top) with numbered menus (menu1). These are separate systems.


Sources: content/guide/site-config.md376-382




YAML Parse Errors


Symptoms: Site generates but configuration section missing


Common Causes:


    

  • Incorrect indentation (YAML requires consistent spaces)
    • 

  • Unquoted strings containing special characters (:, #, @)
    • 

  • Missing quotes around date/time strings
    • 



Example Fix:




Sources: content/guide/site-config.md383-388




Implementation Details


Container Storage Key


The entire configuration is stored in the Container under the key site_config:




Feature Configuration Extraction


The BaseFeature::getConfig() method extracts configuration using the feature's class name:




Sources: content/development/bootstrap.md59-65 content/development/features.md109-122




Related Documentation


Refresh this wiki
On this page