Getting Started

This document provides a quickstart guide for installing StaticForge and generating your first static site. It covers the essential workflow from installation through your first build, introduces the project structure created by site:init, and explains the basic build process using site:render.

For detailed information about the directory structure and file organization, see Project Structure. For comprehensive configuration options, see Configuration System. For in-depth content authoring guidance, see Content Management.

---

Prerequisites

StaticForge requires the following environment:

Requirement	Minimum Version	Purpose
PHP	8.1+	Core runtime
Composer	2.0+	Dependency management
PHP xml extension	-	XML parsing (sitemap generation)
PHP mbstring extension	-	Multibyte string handling

The CLI entry point verifies these requirements at startup and exits with a clear error message if any are missing.

Sources: bin/staticforge.php26-39

---

Installation

StaticForge is distributed as a Composer package. Install it globally or as a project dependency:

Global Installation (Recommended for CLI usage):

Project-Specific Installation:

The installation provides the staticforge CLI command (or vendor/bin/staticforge for project-specific installations). The binary intelligently locates the Composer autoloader regardless of installation method.

Sources: bin/staticforge.php4-23

---

Quick Start Workflow

The following diagram illustrates the complete initialization and first build workflow:

Diagram: StaticForge Initialization and Build Workflow

Sources: src/Commands/InitCommand.php28-75 bin/staticforge.php52-79

---

Step 1: Initialize a New Project

Navigate to your desired project directory and run:

This command performs the following operations:

1. Directory Creation: Creates the standard directory structure
2. Template Installation: Copies the default staticforce template from the package
3. Configuration Files: Creates .env and siteconfig.yaml from bundled examples
4. Sample Content: Generates a starter content/index.md with frontmatter

The InitCommand recursively copies templates from the package location, handling both development and vendor-installed scenarios. It respects existing files unless --force is specified.

Sources: src/Commands/InitCommand.php36-63 src/Commands/InitCommand.php77-112

---

Step 2: Configure Your Site

After initialization, two configuration files require attention:

.env File Configuration

The .env file contains environment-specific settings. At minimum, configure:

This variable is required for URL generation. The audit:config command validates this and other configuration requirements.

siteconfig.yaml Configuration

The siteconfig.yaml file defines site structure and metadata:

This file is version-controlled and shared across environments, while .env contains secrets and environment-specific paths.

Sources: src/Commands/Audit/ConfigCommand.php42-70

---

Step 3: Generate Your Site

Build the static site with:

Build Process Overview

The site:render command orchestrates the following stages:

1. Bootstrap Phase: Loads Composer autoloader, initializes Container with configuration
2. Discovery Phase: FileDiscovery scans content/ directory, parses frontmatter, filters drafts and future-dated content
3. Processing Phase: Fires event lifecycle (CREATE → POST_GLOB → RENDER loop → POST_LOOP)
4. Output Phase: Writes HTML files, copies assets, generates auxiliary files

Sources: bin/staticforge.php52-79

---

Step 4: View Your Site

Start the development server:

This command (provided by a feature) starts a local PHP server serving the public/ directory on http://localhost:8000.

Alternatively, open public/index.html directly in a browser.

---

Project Structure Created by site:init

The InitCommand creates the following directory structure:

Directory Layout Mapping

Directory	Purpose	Version Controlled
content/	Markdown/HTML source files	✓ Yes
templates/	Twig template files	✓ Yes
public/	Generated static site output	✗ No (build artifact)
config/	Optional additional configuration	✓ Yes
logs/	Application and build logs	✗ No
.env	Environment variables and secrets	✗ No (sensitive)
siteconfig.yaml	Site structure and feature config	✓ Yes

For detailed information about each directory's contents and organization patterns, see Project Structure.

Sources: src/Commands/InitCommand.php36-51

---

Configuration Validation

StaticForge provides validation commands to ensure your setup is correct:

audit:config Command

This command validates:

1. Core Configuration: Checks for required SITE_BASE_URL, TEMPLATE, and site.name
2. Directory Structure: Verifies content/ and templates/ directories exist
3. Environment Files: Checks for .env presence
4. Feature Configuration: Validates feature-specific configuration requirements from ConfigurableFeatureInterface implementations

The command groups errors by scope (Core, Environment, Filesystem, Feature) and provides example configuration snippets for missing keys.

Sources: src/Commands/Audit/ConfigCommand.php33-194

---

Understanding the Build Output

After running site:render, the public/ directory contains:

public/
├── index.html # Generated from content/index.md
├── assets/ # CSS, JS from features
│ └── styles.css
├── sitemap.xml # Auto-generated by Sitemap feature
├── robots.txt # Auto-generated by RobotsTxt feature
└── search.json # Search index from Search feature

Each file in content/ becomes an HTML file in public/, preserving the directory structure. The URL transformation logic removes the source extension and adds .html, with category-based routing applied if the frontmatter contains a category field.

---

Common First-Build Issues

Issue	Cause	Solution
"Missing SITE_BASE_URL"	.env not configured	Edit .env and set SITE_BASE_URL=http://localhost:8000
"Content directory not found"	Wrong working directory	Run staticforge commands from project root
"Template not found"	Missing or misconfigured template	Verify templates/staticforce/ exists or set TEMPLATE in .env
Empty public/ directory	No content files discovered	Add .md or .html files to content/ with valid frontmatter

Run staticforge audit:config to diagnose configuration issues before building.

Sources: src/Commands/Audit/ConfigCommand.php42-70

---

Next Steps

After successfully generating your first site:

1. Add Content: Create additional Markdown or HTML files in content/. See Content Management for frontmatter syntax and content organization patterns.

2. Customize Templates: Modify templates in templates/ to change your site's appearance. See Template System for Twig template inheritance and variable reference.

3. Enable Features: Configure features in siteconfig.yaml to add functionality like search, RSS feeds, and category indexes. See Built-in Features Reference.

4. Validate Content: Run staticforge audit:content to check frontmatter validity, internal links, and content integrity. See Audit Commands.

5. Deploy: Use staticforge site:upload or staticforge make:htaccess to prepare for production deployment. See Deployment Features.

Sources: src/Commands/InitCommand.php66-72