Built-in Features Overview

This document catalogs all features shipped with StaticForge, organized by functional category. Each feature is a self-contained plugin that hooks into the event system to extend site generation capabilities.

For detailed documentation on individual features, see Built-in Features Reference. For information on creating your own features, see Creating Custom Features. For community-maintained features available via Composer, see External Features.

---

Feature Categories

StaticForge ships with 12 built-in features organized into five functional domains. Each feature lives in its own directory under vendor/eicc/staticforge/src/Features/ and implements FeatureInterface.

Content Renderers

MarkdownRenderer and HtmlRenderer process content files and convert them to HTML.

Feature	File Extension	Event	Purpose
MarkdownRenderer	.md	RENDER (priority 100)	Converts Markdown to HTML using CommonMark
HtmlRenderer	.html, .htm	RENDER (priority 100)	Wraps HTML content in templates

Both renderers extend BaseRendererFeature and use TemplateRenderer to apply Twig templates.

Navigation & Structure Features

These features organize content and build navigation elements.

Feature	Metadata Field	Event	Purpose
MenuBuilder	menu	POST_GLOB (priority 100)	Generates navigation menus from frontmatter
Categories	category	POST_GLOB (priority 50)	Routes files into subdirectories by category
CategoryIndex	type: category	POST_LOOP (priority 200)	Generates index pages listing category contents
Tags	tags	POST_RENDER (priority 100)	Collects and aggregates tag metadata

Priority matters: Categories runs at priority 50 before MenuBuilder at priority 100, ensuring category directories exist before menu generation.

SEO & Discovery Features

These features generate auxiliary files for search engines and feed readers.

Feature	Output File	Event	Purpose
Sitemap	sitemap.xml	POST_LOOP (priority 100)	Generates XML sitemap for search engines
RssFeed	{category}/rss.xml	POST_LOOP (priority 100)	Creates RSS feeds per category
RobotsTxt	robots.txt	POST_LOOP (priority 100)	Generates robots.txt with disallow rules

All three features collect data during POST_RENDER and write files during POST_LOOP.

Interactive Features

These features add client-side functionality to static sites.

Feature	Shortcode	Assets	Purpose
Forms	[form name="..."]	form.js, form.css	Embeds AJAX forms with Altcha spam protection
Search	[search]	search.js, search.json	Client-side full-text search using MiniSearch

Both features use AssetManager to inject JavaScript and CSS into templates.

Deployment & Optimization Features

These features prepare sites for production deployment.

Feature	Variable	Event	Purpose
CacheBuster	cache_buster	CREATE (priority 100)	Generates unique build ID for asset versioning
TemplateAssets	styles, scripts	POST_GLOB (priority 100)	Manages CSS/JS asset registration and injection

CacheBuster runs during CREATE to make the build ID available to all subsequent stages.

Sources:

• content/features/index.md1-177
• Diagram 1 and Diagram 3 from high-level architecture

---

Feature Discovery System

Loading Priority

Features are discovered and loaded from three sources with explicit precedence:

Priority Semantics:

1. User Features (highest): Located in src/Features/, these override library features with matching names
2. Composer Features (medium): Declared via extra.staticforge.feature in third-party packages
3. Library Features (lowest): Shipped with StaticForge in vendor/eicc/staticforge/src/Features/

If a feature named "MarkdownRenderer" exists in both src/Features/MarkdownRenderer/ and vendor/eicc/staticforge/src/Features/MarkdownRenderer/, only the user version loads.

Sources:

• src/Core/FeatureManager.php52-96
• src/Core/FeatureManager.php146-231
• src/Core/FeatureManager.php286-327

Feature Discovery Flow

Discovery Logic:

1. Directory Scan: FeatureManager uses DirectoryIterator to find subdirectories containing Feature.php
2. Class Resolution: Tries multiple namespace patterns (user namespaces first, then EICC\StaticForge\Features\{DirectoryName}\Feature)
3. Duplicate Prevention: If a feature name is already loaded, subsequent discoveries are skipped
4. Disabled Feature Check: Features in siteconfig.yaml disabled_features list are logged but not registered
5. Registration: Each feature's register() method is called with EventManager and Container references

Sources:

• src/Core/FeatureManager.php160-182
• src/Core/FeatureManager.php187-231
• src/Core/FeatureManager.php240-280

---

Feature-Event Mapping

Each feature hooks into specific lifecycle events to perform its work:

Event Timing Strategies:

• CREATE: One-time initialization (e.g., generate cache buster ID)
• POST_GLOB: Work requiring complete file catalog (e.g., build site-wide menus)
• RENDER: Per-file content transformation (e.g., Markdown to HTML)
• POST_RENDER: Per-file data collection (e.g., gather URLs for sitemap)
• POST_LOOP: Aggregate operations after all files processed (e.g., write sitemap.xml)

Sources:

• Diagram 2 from high-level architecture (Event-Driven Generation Lifecycle)
• src/Core/FeatureManager.php223-227

---

Complete Feature Reference

Built-in Features by Source Location

All built-in features reside in vendor/eicc/staticforge/src/Features/{FeatureName}/Feature.php:

Feature Name	Class	Service Classes	Configuration
CacheBuster	EICC\StaticForge\Features\CacheBuster\Feature	None	None
Categories	EICC\StaticForge\Features\Categories\Feature	None	None
CategoryIndex	EICC\StaticForge\Features\CategoryIndex\Feature	CategoryService, ImageService, IndexGenerator	Optional: Imagick for thumbnails
Forms	EICC\StaticForge\Features\Forms\Feature	FormService, FormConfigLoader, FormAssetService	siteconfig.yaml: forms section
HtmlRenderer	EICC\StaticForge\Features\HtmlRenderer\Feature	ContentExtractor	None
MarkdownRenderer	EICC\StaticForge\Features\MarkdownRenderer\Feature	MarkdownProcessor, ContentExtractor	None
MenuBuilder	EICC\StaticForge\Features\MenuBuilder\Feature	MenuScanner, MenuHtmlGenerator	None
RobotsTxt	EICC\StaticForge\Features\RobotsTxt\Feature	None	None
RssFeed	EICC\StaticForge\Features\RssFeed\Feature	RssFeedService, RssBuilder	None
Search	EICC\StaticForge\Features\Search\Feature	SearchIndexService, SearchAssetService	siteconfig.yaml: search section
Sitemap	EICC\StaticForge\Features\Sitemap\Feature	SitemapService	None
Tags	EICC\StaticForge\Features\Tags\Feature	None	None
TemplateAssets	EICC\StaticForge\Features\TemplateAssets\Feature	AssetManager, AssetCollector	None

Feature Dependencies

Critical Dependencies:

• Categories → MenuBuilder: Categories must run first (priority 50) to establish subdirectory structure before menus are built (priority 100)
• TemplateAssets → Forms/Search: Interactive features depend on AssetManager for JS/CSS injection
• All Features → Container: All features access configuration and services via dependency injection
• All Features → EventManager: All features register event listeners for lifecycle hooks

Sources:

• content/features/index.md156-171
• Diagram 3 from high-level architecture (Feature System Architecture)

---

Disabling Features

Via Configuration

Add feature names to siteconfig.yaml:

Features in this list are discovered but not registered with EventManager. They are marked with status 'disabled' in FeatureManager::featureStatuses.

Via Directory Removal

Delete or rename the feature directory:

This prevents the feature from being discovered during the directory scan.

Safety Considerations

Safe to Disable:

• RssFeed: Only affects RSS generation; site functions normally without feeds
• Sitemap: Only affects sitemap.xml; site renders completely
• RobotsTxt: Only affects robots.txt; site works without it
• Tags: Only affects tag metadata collection
• Search: Only affects search functionality
• Forms: Only affects form shortcodes
• CategoryIndex: Only affects index page generation

Use Caution When Disabling:

• MarkdownRenderer: Required to process .md files; disabling breaks Markdown content
• HtmlRenderer: Required to process .html files; disabling breaks HTML content
• Categories: Required to create subdirectories; content will render flat
• MenuBuilder: Required for automatic navigation; menus must be manually created
• TemplateAssets: Required for asset management; CSS/JS injection may fail

Sources:

• src/Core/FeatureManager.php59-63
• src/Core/FeatureManager.php210-214
• content/features/index.md122-149

---

Feature Type Identification

Features are tagged with one of three types:

Type	Source	Priority	Example
Custom	src/Features/	Highest (overrides library)	User-created features or library overrides
Composer	Third-party packages	Medium	External features via composer require
Standard	vendor/eicc/staticforge/src/Features/	Lowest (can be overridden)	Built-in features shipped with StaticForge

Feature types are stored in FeatureManager::featureTypes and exposed via Container variable features:

This allows features and templates to query feature provenance at runtime.

Sources:

• src/Core/FeatureManager.php86-93
• src/Core/FeatureManager.php146-154
• src/Core/FeatureManager.php361-364

---

Service-Oriented Feature Architecture

Complex features delegate logic to dedicated service classes:

Service Responsibilities:

• Feature Classes (Feature.php): Event registration, lifecycle management, orchestration
• Service Classes: Business logic, data transformation, file I/O
• Model Classes: Data structures (e.g., FeedChannel, FeedItem, Category)

This separation keeps feature classes focused on event handling while isolating domain logic in testable service classes.

Sources:

• src/Features/RssFeed/Services/RssFeedService.php1-305
• src/Features/CategoryIndex/Services/CategoryService.php1-135
• src/Features/CategoryIndex/Services/ImageService.php1-111
• src/Features/Sitemap/Services/SitemapService.php1-123
• Diagram 3 from high-level architecture (Feature System Architecture)

---

External vs Built-in Features

Built-in Features

Shipped with StaticForge core, loaded from vendor/eicc/staticforge/src/Features/:

• Maintained by core team
• Versioned with StaticForge releases
• Loaded automatically unless disabled
• Type: Standard

External Features

Distributed as separate Composer packages, discovered via composer/installed.json:

• Maintained by community or core team as extensions
• Independent versioning
• Installed via composer require vendor/package-name
• Declared via extra.staticforge.feature in composer.json
• Type: Composer

Example External Features:

Package	Feature	Purpose
calevans/staticforge-chapternav	ChapterNavigation	Sequential prev/next navigation
calevans/staticforge-google-analytics	GoogleAnalytics	GA tracking code injection
calevans/staticforge-podcast	Podcast	Podcast RSS extensions
calevans/staticforge-s3	S3MediaOffload	AWS S3 media hosting
calevans/staticforge-social-metadata	SocialMetadata	Open Graph and Twitter Cards

For complete list and installation instructions, see External Features.

Sources:

• content/features/external-features.md1-57
• src/Core/FeatureManager.php286-327

---

Next Steps

• For detailed feature documentation, see Built-in Features Reference
• To create custom features, see Creating Custom Features
• To install external features, see External Features
• To understand the event system, see Event System