Basic Usage

This document covers the fundamental workflow of using StaticForge: creating content files, generating your static site with the site:render command, and viewing the results locally. This assumes you have already completed installation and project initialization (see Installation & Project Setup) and understand the project directory structure (see Project Structure).

For detailed information about content management features like frontmatter metadata, URL generation, and advanced processing, see Content Management. For template customization, see Template System.

---

Basic Workflow Overview

The StaticForge workflow consists of three primary steps: creating content, generating the site, and viewing the output.

Workflow Diagram: Content to Static Site

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php1-292 src/Core/FileDiscovery.php (referenced in diagrams), tests/Integration/Commands/RenderSiteCommandTest.php82-98

---

Creating Content Files

StaticForge processes two types of content files: Markdown (.md) and HTML (.html). Both support frontmatter metadata for configuration.

Markdown Content Files

Markdown files use YAML frontmatter delimited by --- at the beginning of the file:

File Structure:

content/
├── index.md # Homepage
├── about.md # About page
└── blog/
 └── post1.md # Blog post

Sources: tests/Integration/Commands/RenderSiteCommandTest.php59-66 src/Commands/InitCommand.php146-182 tests/Integration/RssFeedIntegrationTest.php102-110

HTML Content Files

HTML files use frontmatter wrapped in HTML comments:

Sources: tests/Integration/Commands/RenderSiteCommandTest.php59-66 tests/Integration/Features/RobotsTxtIntegrationTest.php202-212

Common Frontmatter Fields

Field	Type	Purpose	Example
title	string	Page title	"Welcome to My Site"
description	string	Meta description	"A comprehensive guide"
template	string	Template override	"staticforce" or "docs"
category	string	Content category	"Technology"
tags	array	Content tags	["tutorial", "beginner"]
draft	boolean	Hide from production	true
date	string	Publication date	"2024-01-15"
robots	string	Search indexing	"yes" or "no"
menu	string	Menu position	"1.2" or "top"

Sources: tests/Integration/RssFeedIntegrationTest.php102-121 tests/Integration/Features/RobotsTxtIntegrationTest.php83-91 content/development/templates.md (referenced in high-level diagrams)

---

Running site:render

The site:render command is the primary tool for generating your static site. It scans the content/ directory, processes all files, applies templates, and writes HTML output to the public/ directory.

Basic Usage

Command Execution Flow:

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php58-171 tests/Integration/Commands/RenderSiteCommandTest.php82-98

Basic Command

This command:

1. Scans the content/ directory for .md and .html files
2. Parses frontmatter metadata from each file
3. Filters out drafts and future-dated content (unless configured otherwise)
4. Converts Markdown to HTML
5. Applies templates from templates/ directory
6. Writes output to public/ directory

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php58-157 tests/Integration/Commands/RenderSiteCommandTest.php82-98

Command Options

Available Options Table:

Option	Short	Type	Description	Example
--clean	-c	Flag	Delete public/ directory before generation	--clean
--template	-t	Value	Override site template	--template staticforce
--input	-i	Value	Override content source directory	--input content/
--output	-o	Value	Override output directory	--output build/
-v, -vv, -vvv	N/A	Flag	Verbose output (1-3 levels)	-vv

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php29-56 tests/Integration/Commands/RenderSiteCommandTest.php103-121

Clean Option

The --clean flag removes all existing files in the output directory before generation:

What it does:

1. Deletes the entire OUTPUT_DIR (default: public/)
2. Recreates the directory structure
3. Proceeds with site generation

Use case: Ensures no stale files remain from previous builds when files are renamed or deleted from content/.

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php108-118 src/Features/SiteBuilder/Commands/RenderSiteCommand.php250-268 tests/Integration/Commands/RenderSiteCommandTest.php126-148

Template Override

The --template option allows runtime template selection:

Template Resolution Priority:

CLI --template flag > siteconfig.yaml['site']['template'] > .env TEMPLATE > "staticforce" default

This enables:

• Testing different templates without editing configuration
• Per-deployment template selection
• Development vs. production template switching

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php66-89 tests/Integration/Commands/RenderSiteCommandTest.php153-183

Directory Overrides

Override input and output directories for non-standard workflows:

Use cases:

• Building multiple sites from different content sources
• Testing content in isolation
• Deploying to non-standard directories

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php73-101 tests/Integration/Commands/RenderSiteCommandTest.php244-280 tests/Integration/Commands/RenderSiteCommandTest.php319-363

Verbose Output

Verbose flags provide detailed generation information:

Verbose Output Includes:

• Configuration values (SOURCE_DIR, OUTPUT_DIR, TEMPLATE)
• Event pipeline stages
• Active features list (standard vs. custom)
• Generation statistics (file count, time per file)
• Stack traces on errors

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php103-155 src/Features/SiteBuilder/Commands/RenderSiteCommand.php179-248

---

Generation Process Details

Event Pipeline Execution:

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php120-143 (pipeline documentation in verbose output), Diagram 2 from high-level architecture overview

Key Processing Stages

CREATE Event:

• Features initialize internal state
• CacheBuster generates unique build_id timestamp
• Container variables are set up

Sources: src/Features/CacheBuster/Feature.php42-52 tests/Unit/Features/CacheBusterFeatureTest.php31-51

File Discovery:

• FileDiscovery recursively scans SOURCE_DIR
• Extracts frontmatter from .md and .html files
• Filters files with draft: true (unless SHOW_DRAFTS=true)
• Filters files with future date values
• Generates URLs based on file paths and categories

Sources: Referenced in src/Core/FileDiscovery.php tests/Integration/Commands/RenderSiteCommandTest.php58-67

POST_GLOB Event:

• Features that need the complete file catalog execute
• MenuBuilder constructs navigation from frontmatter
• CategoryIndex creates category listing pages
• Priority ordering ensures dependencies are satisfied

Sources: High-level architecture Diagram 2 (Event-Driven Generation Lifecycle)

Render Loop: For each file:

• PRE_RENDER: Metadata enrichment
• RENDER: Content transformation (Markdown→HTML)
• POST_RENDER: Data collection (search indexing, URL collection)
• File Write: HTML written to OUTPUT_DIR

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php125-133

POST_LOOP Event:

• Site-wide artifacts generated
• RSS feeds written to category directories
• Sitemap.xml generated
• Robots.txt created

Sources: tests/Integration/RssFeedIntegrationTest.php99-166 tests/Integration/Features/RobotsTxtIntegrationTest.php80-109

---

Viewing the Generated Site

After running site:render, your static site is in the public/ directory (or the directory specified by OUTPUT_DIR).

Output Directory Structure

public/
├── index.html # Homepage (from content/index.md)
├── about.html # About page (from content/about.md)
├── blog/
│ ├── post1.html # Blog post (from content/blog/post1.md)
│ └── post2.html
├── technology/
│ ├── tech-article.html # Categorized content
│ └── rss.xml # Category RSS feed
├── assets/
│ ├── css/
│ └── js/
├── sitemap.xml # Generated by Sitemap feature
└── robots.txt # Generated by RobotsTxt feature

Sources: tests/Integration/RssFeedIntegrationTest.php135-145 tests/Integration/Features/RobotsTxtIntegrationTest.php99-109

Using site:devserver

StaticForge includes a built-in development server for local testing:

Default behavior:

• Serves files from public/ directory
• Listens on localhost:8000
• Provides live access to generated site

Viewing your site:

1. Run site:devserver in your terminal
2. Open browser to http://localhost:8000
3. Navigate through your generated pages

Note: The development server serves static files only. It does not provide live-reload or automatic regeneration. To see content changes, re-run site:render and refresh your browser.

Sources: Referenced in page purpose, standard PHP development server pattern

Manual Viewing

Alternatively, open HTML files directly:

Or use any web server that can serve static files (Apache, Nginx, Python's http.server, etc.).

Sources: Standard static site deployment pattern

---

Quick Start Example

Here's a complete end-to-end example of creating content and generating a site.

Step 1: Create Content

Create content/index.md:

Create content/blog/first-post.md:

Sources: src/Commands/InitCommand.php146-182 tests/Integration/RssFeedIntegrationTest.php102-124

Step 2: Generate the Site

Expected output:

StaticForge Site Generator

Starting site generation...

✅ Site generation completed successfully!
Time: 0.15s

Sources: tests/Integration/Commands/RenderSiteCommandTest.php92-97 src/Features/SiteBuilder/Commands/RenderSiteCommand.php148-156

Step 3: View the Results

Generated files:

public/
├── index.html # Your homepage
├── blog/
│ ├── first-post.html # Your blog post
│ └── rss.xml # RSS feed for Blog category
├── sitemap.xml
└── robots.txt

Sources: tests/Integration/RssFeedIntegrationTest.php135-145

Step 4: Verify Content

Check generated HTML:

The output will include:

• Your content rendered as HTML
• Template wrapper with site navigation
• Meta tags from frontmatter
• Cache-busting query parameters on assets

Check category RSS feed:

This will contain:

• Channel metadata (site name, category name)
• Item entries for each blog post
• Proper XML structure with <rss> root element

Sources: tests/Integration/RssFeedIntegrationTest.php138-165 tests/Integration/Features/RobotsTxtIntegrationTest.php98-105

---

Common Workflows

Development Workflow

Sources: Standard development pattern

Testing Different Templates

Sources: tests/Integration/Commands/RenderSiteCommandTest.php153-183

Building for Production

Sources: tests/Integration/Commands/RenderSiteCommandTest.php126-148

---

Error Handling

Common Errors

Invalid Template:

Site generation failed:
Template 'nonexistent' not found in templates/
Available templates: sample, staticforce, docs

Solution: Use --template with a valid template name from templates/ directory.

Sources: tests/Integration/Commands/RenderSiteCommandTest.php188-207

Invalid Input Directory:

Site generation failed:
Input directory does not exist: /nonexistent/directory

Solution: Ensure the --input path exists or omit the option to use default content/ directory.

Sources: tests/Integration/Commands/RenderSiteCommandTest.php368-386

Verbose Debugging

For detailed error information:

This shows:

• Full stack traces
• Event execution sequence
• Feature processing details
• Configuration values

Sources: src/Features/SiteBuilder/Commands/RenderSiteCommand.php163-168

---

Next Steps

After mastering basic usage, explore:

• Content Files & Frontmatter - Advanced metadata fields and content organization
• Template System - Customizing page layouts and styling
• Built-in Features Reference - Leveraging search, forms, categories, and more
• CLI Commands - Additional commands for auditing and deployment

Sources: Table of contents structure