Last indexed: 11 February 2026 (5f6a2a)

Project Structure

This page documents the standard directory layout of a StaticForge project, explaining the purpose of each directory and configuration file. Understanding this structure is essential for organizing content, templates, and features in your static site.

For information about configuring directory paths, see Configuration Resolution. For details on creating content within the content/ directory, see Content Files & Frontmatter.

Project Layout Overview

A StaticForge project consists of a well-defined directory structure that separates concerns between configuration, content, templates, and generated output. The structure supports both library-based installations (via Composer) and standalone development installations.

Sources: composer.json1-60 .env.example1-42 src/bootstrap.php79-123

Standard Directory Structure

The following diagram illustrates the complete directory structure of a StaticForge project:

Directory Classification:

Blue nodes: Version-controlled directories/files (committed to Git)
Red nodes: Generated directories/files (excluded from version control)
Yellow nodes: Secret files (excluded from version control)

Sources: .gitignore1-24 composer.json38-46 .env.example7-11

Core Directories

`content/` - Source Content Directory

The content directory contains all source files (Markdown and HTML) that will be processed into the static site. Files can be organized in any subdirectory structure, which will be preserved in the output.

Aspect	Details
Default Path	`content/`
Environment Variable	`SOURCE_DIR`
File Types	`.md`, `.html`
Version Control	✅ Committed
Purpose	Store all page content with frontmatter metadata

Configuration:

Specified via SOURCE_DIR in .env or defaults to content/ src/bootstrap.php113
Normalized to absolute path during bootstrap src/bootstrap.php96-109

Sources: .env.example8 src/bootstrap.php113

`templates/` - Twig Template Directory

Contains Twig templates organized by theme. Each theme is a subdirectory containing template files that control the HTML structure and layout of generated pages.

Aspect	Details
Default Path	`templates/`
Environment Variable	`TEMPLATE_DIR`
Active Theme	Specified via `TEMPLATE` variable or `siteconfig.yaml`
Version Control	✅ Committed
Purpose	Define HTML layouts and structure

Template Resolution:

The active template is selected from siteconfig.yaml['site']['template'], falling back to $_ENV['TEMPLATE'], finally defaulting to staticforce src/bootstrap.php178-186
Template loader adds the active theme directory to Twig's path src/bootstrap.php218-224

Sources: .env.example10 src/bootstrap.php114-224

`public/` - Generated Output Directory

The output directory receives all generated HTML files, along with assets and auxiliary files created by features. This directory should be served by a web server or uploaded to hosting.

Aspect	Details
Default Path	`public/`
Environment Variable	`OUTPUT_DIR`
Version Control	❌ Excluded (`.gitignore`)
Purpose	Static site ready for deployment

Contents:

Generated HTML files (mirrors content/ structure)
assets/ subdirectory for CSS, JavaScript, images
Auxiliary files: sitemap.xml, robots.txt, RSS feeds

Sources: .env.example9 src/bootstrap.php115 .gitignore4

`src/Features/` - Custom Features Directory

User-defined features that extend StaticForge functionality. Features in this directory have the highest priority and can override core features.

Aspect	Details
Default Path	`src/Features/`
Environment Variable	`FEATURES_DIR`
Version Control	✅ Committed
Priority	Highest (overrides library features)

Feature Discovery: Features are loaded in priority order: user features → Composer features → library features. See Feature Architecture for details on creating custom features.

Sources: .env.example11

`vendor/` - Composer Dependencies

Standard Composer directory containing all PHP dependencies, including the StaticForge core library itself when installed as a dependency.

Aspect	Details
Path	`vendor/` (fixed)
Version Control	❌ Excluded (`.gitignore`)
Core Library	`vendor/eicc/staticforge/`
Autoloader	`vendor/autoload.php`

Bootstrap Process: The bootstrap file searches multiple paths for the autoloader to support both development and library installations src/bootstrap.php26-39

Sources: composer.json38-46 src/bootstrap.php26-44 .gitignore2

`bin/` - CLI Executables

Contains the main CLI entry point for StaticForge commands.

Aspect	Details
Path	`bin/`
Main Executable	`bin/staticforge.php`
Version Control	✅ Committed
Usage	`php bin/staticforge.php <command>`

Executable Declaration: Registered as a Composer binary composer.json57-59 allowing invocation via vendor/bin/staticforge.php in library installations.

Sources: composer.json57-59

`logs/` - Application Logs

Directory for log files generated during site builds and command execution.

Aspect	Details
Default Path	`logs/`
Environment Variable	`LOG_DIR`, `LOG_FILE`
Version Control	❌ Excluded (`.gitignore`)
Default File	`logs/staticforge.log`

Configuration:

LOG_DIR defaults to logs/ src/bootstrap.php116
LOG_FILE defaults to ${LOG_DIR}/staticforge.log src/bootstrap.php119-123
Directory is created automatically if missing src/bootstrap.php196-201

Sources: .env.example14-15 src/bootstrap.php116-201 .gitignore7

Configuration Files

The following diagram shows the relationship between configuration files and the directories they control:

Sources: src/bootstrap.php61-186

`.env` - Environment Configuration

Environment-specific configuration file for infrastructure settings and secrets. This file should not be committed to version control.

Key Sections:

Section	Variables	Purpose
Site URLs	`SITE_BASE_URL`, `UPLOAD_URL`	Base URL and deployment target
Directories	`SOURCE_DIR`, `OUTPUT_DIR`, `TEMPLATE_DIR`, `FEATURES_DIR`	Path configuration
Logging	`LOG_LEVEL`, `LOG_FILE`	Log verbosity and location
SFTP	`SFTP_HOST`, `SFTP_USERNAME`, `SFTP_PASSWORD`, etc.	Upload credentials
S3	`S3_BUCKET`, `S3_REGION`, `S3_ACCESS_KEY`, etc.	Cloud storage

Loading Process:

Bootstrap searches for .env in current working directory src/bootstrap.php64-77
Variables are loaded into $_ENV superglobal using Dotenv src/bootstrap.php72-73
Default values are applied for missing variables src/bootstrap.php113-126
All paths are normalized to absolute paths src/bootstrap.php96-109

Sources: .env.example1-42 src/bootstrap.php61-126

`siteconfig.yaml` - Site Configuration

Version-controlled configuration file for site metadata, menus, and feature settings. Unlike .env, this file contains non-sensitive data and should be committed.

Typical Structure:

Loading:

Searched in current working directory and app root src/bootstrap.php146-168
Parsed using Symfony YAML parser src/bootstrap.php155
Stored in Container as site_config variable src/bootstrap.php171

Sources: src/bootstrap.php143-171

`composer.json` - Project Manifest

Defines project dependencies, autoloading configuration, and metadata.

Key Sections for StaticForge:

Binary Declaration: StaticForge registers bin/staticforge.php as an executable composer.json57-59 making it available at vendor/bin/staticforge.php after installation.

Sources: composer.json1-60

Directory Resolution Logic

The following diagram illustrates how StaticForge resolves directory paths during bootstrap:

Path Normalization Algorithm:

The normalizePath function src/bootstrap.php96-109 applies the following logic:

Check if absolute: Path starts with / (Unix) or matches [A-Z]:\ (Windows) → use as-is
Check for stream wrapper: Path contains :// (e.g., vfs://) → use as-is
Otherwise: Prepend app_root to make absolute

Application Root Discovery:

The bootstrap traverses up from getcwd() searching for composer.json or .env src/bootstrap.php79-93:

Sources: src/bootstrap.php79-126

Development vs. Library Installation

StaticForge supports two installation modes with slightly different directory structures:

Development Installation (Git Clone)

project-root/
├── bin/staticforge.php # Direct access
├── src/ # Core source (editable)
│ ├── Core/
│ ├── Features/
│ └── bootstrap.php
├── templates/ # Templates included
├── content/ # Example content included
├── vendor/ # Composer dependencies
├── composer.json # Development manifest
└── .env # Created from .env.example

Characteristics:

Core source code is directly editable
Templates pre-installed in templates/
Example content provided
Full test suite available

Sources: README.md23-32

Library Installation (Composer Require)

project-root/
├── vendor/
│ ├── autoload.php
│ ├── eicc/staticforge/ # Core library (read-only)
│ │ ├── bin/staticforge.php
│ │ ├── src/
│ │ └── templates/ # Template source
│ └── bin/
│ └── staticforge.php # Symlink to executable
├── templates/ # Copied from library on install
├── content/ # Created by user
├── src/Features/ # User features (optional)
├── composer.json # User's project manifest
└── .env # Created by user

Characteristics:

Core library installed in vendor/eicc/staticforge/
Templates copied to project root by scripts/install-templates.php scripts/install-templates.php1-107
User creates content/ and .env manually
Executable available at vendor/bin/staticforge.php

Template Installation:

The install-templates.php script scripts/install-templates.php37-76 copies templates from the library to the project root without overwriting existing files, allowing users to customize templates while preserving updates.

Sources: scripts/install-templates.php11-76 README.md14-21

Directory Creation and Permissions

Automatic Directory Creation

StaticForge automatically creates the following directories if they don't exist:

Directory	Creation Point	Permissions
Log Directory	During logger initialization	`0755`
Template Directory	During Twig initialization	`0755`

Implementation:

Logger checks and creates LOG_DIR src/bootstrap.php196-201
Twig checks and creates TEMPLATE_DIR src/bootstrap.php212-216

Manual Directory Creation

The following directories must be created manually or by commands:

Directory	Created By	When
`content/`	User or `site:init`	Before first render
`public/`	`site:render` command	During build
`src/Features/`	User	When adding custom features

Sources: src/bootstrap.php196-216

Summary

The StaticForge project structure is designed with clear separation of concerns:

Source files (content/, templates/, src/Features/) are version-controlled
Generated files (public/, logs/) are excluded from version control
Secret files (.env) are excluded and must be created per environment
Configuration files (.env, siteconfig.yaml) provide a two-tier config system
Path resolution normalizes all paths to absolute during bootstrap

This structure supports both local development and library-based installations, with automatic path resolution ensuring commands work regardless of the current working directory.

Sources: composer.json1-60 src/bootstrap.php1-257 .env.example1-42 .gitignore1-24 scripts/install-templates.php1-107

Refresh this wiki

URL: https://deepwiki.com/calevans/staticforge/2.2-project-structure