URL Generation

This document describes how StaticForge generates URLs for content files during the discovery phase. URL generation transforms source file paths into web-accessible URLs that reflect the site's information architecture.

For information about how content files are discovered and filtered before URL generation, see File Discovery & Processing. For information about category organization features, see Navigation & Structure Features.

---

Overview

URL generation occurs during the file discovery phase, before any rendering takes place. Each discovered file receives a canonical URL that is used throughout the build process for internal linking, sitemap generation, search indexing, and navigation structures.

The URL generation system implements a deterministic transformation pipeline that converts filesystem paths into web URLs, with optional category-based routing modifications.

Sources: src/Core/FileDiscovery.php222-269

---

URL Generation Pipeline

The following diagram shows the complete URL generation process, from source file to final URL:

Diagram: URL Generation Process Flow

Sources: src/Core/FileDiscovery.php85-128 src/Core/FileDiscovery.php229-269

---

Basic URL Transformation

The generateUrl() method implements a multi-stage transformation that converts a source file path into a web-accessible URL.

Diagram: URL Transformation Steps

Step	Operation	Example Input	Example Output
1	Remove SOURCE_DIR prefix	/var/www/content/blog/post.md	blog/post.md
2	Replace extension with .html	blog/post.md	blog/post.html
3	Apply category routing (if present)	blog/post.html + {category: 'Tech'}	tech/post.html
4	Prepend SITE_BASE_URL	tech/post.html	https://example.com/tech/post.html

Sources: src/Core/FileDiscovery.php229-269

Implementation Details

The URL generation method requires two container variables:

• SOURCE_DIR: Absolute path to the content directory
• SITE_BASE_URL: Base URL for the site (with trailing slash handling)

Sources: src/Core/FileDiscovery.php229-269

---

Category-Based URL Routing

When content files include a category field in their frontmatter, the URL generation system modifies the URL structure to include the category as a subdirectory.

Diagram: Category URL Modification Logic

Sources: src/Core/FileDiscovery.php242-255

Category URL Rules

Scenario	Input Path	Category	Output URL
Root-level file	post.md	Tech	/tech/post.html
Nested file	blog/post.md	Tech	/blog/post.html (preserves structure)
Multi-word category	post.md	Web Development	/web-development/post.html
Special characters	post.md	C# Programming	/c-programming/post.html

The category routing logic only applies to files in the root of SOURCE_DIR. Files already in subdirectories preserve their existing directory structure to prevent conflicts.

Sources: src/Core/FileDiscovery.php242-255

---

URL Slugification

Category names are converted to URL-safe slugs using the slugify() method. This ensures consistent, web-friendly URLs regardless of the original category name format.

Slugification Algorithm

Input Category	Slugified Output
Technology	technology
Web Dev	web-dev
C# Programming	c-programming
Multiple Spaces	multiple-spaces
__Special__	special

Sources: src/Core/FileDiscovery.php271-295 src/Features/Categories/Services/CategoriesService.php133-148

---

URL Storage and Access

Generated URLs are stored in the discovered_files container variable during the discovery phase. This data structure becomes the single source of truth for all file URLs throughout the build process.

Diagram: Discovered Files Data Structure

Sources: src/Core/FileDiscovery.php122-127 src/Core/FileDiscovery.php45-46

Discovered Files Schema

Each entry in discovered_files contains:

Field	Type	Description	Example
path	string	Absolute filesystem path to source file	/var/www/content/blog/post.md
url	string	Full web URL including SITE_BASE_URL	https://example.com/tech/post.html
metadata	array	Parsed frontmatter metadata	['title' => 'My Post', 'category' => 'Tech']

Sources: src/Core/FileDiscovery.php33-34

---

Category Output Path Modification

While URL generation happens during discovery, the Categories feature can further modify the output path during rendering. This is separate from URL generation but creates consistency between URLs and filesystem output.

Diagram: Category Output Path Workflow

Sources: src/Features/Categories/Feature.php66-90 src/Features/Categories/Services/CategoriesService.php105-131

Output Path Transformation

The categorizeOutputPath() method ensures files are written to category-specific subdirectories:

Input Output Path	Category	Result Output Path	Notes
/var/www/public/post.html	Tech	/var/www/public/tech/post.html	Category added
/var/www/public/tech/post.html	Tech	/var/www/public/tech/post.html	Already in category, no change
/var/www/public/blog/post.html	Tech	/var/www/public/tech/post.html	Category replaces existing subdir

The method includes duplicate prevention logic to avoid double-nesting (e.g., public/tech/tech/).

Sources: src/Features/Categories/Services/CategoriesService.php105-131

---

URL Usage Across Features

Generated URLs are consumed by multiple features throughout the build pipeline. Each feature accesses URLs from the discovered_files array stored in the container.

Feature URL Consumption Patterns

Feature	Usage	Code Reference
Search	Calculates URLs for search index entries	src/Features/Search/Services/SearchIndexService.php227-238
MenuBuilder	Uses URLs for static menu links (with base URL prepending)	src/Features/MenuBuilder/Services/StaticMenuProcessor.php62-71
RobotsTxt	Converts file paths to relative URLs for disallow rules	src/Features/RobotsTxt/Services/RobotsTxtService.php164-187
Sitemap	Collects URLs from discovered files for sitemap.xml	Sitemap feature uses URL field directly

Sources: src/Features/Search/Services/SearchIndexService.php28-78 src/Features/MenuBuilder/Services/StaticMenuProcessor.php26-99 src/Features/RobotsTxt/Services/RobotsTxtService.php34-54

---

URL Calculation Methods

Different features implement URL calculation methods for specific purposes. These methods typically work with either the stored URL from discovered_files or calculate relative URLs from output paths.

Diagram: URL Calculation Methods by Feature

SearchIndexService.calculateUrl()

Converts an output path to a full URL by removing OUTPUT_DIR and prepending SITE_BASE_URL:

Sources: src/Features/Search/Services/SearchIndexService.php227-238

RobotsTxtService.calculateWebPath()

Converts a source file path to a relative web path for robots.txt disallow entries:

Sources: src/Features/RobotsTxt/Services/RobotsTxtService.php164-187

---

Configuration Requirements

URL generation requires specific container variables to be configured during bootstrap:

Variable	Required	Purpose	Example
SOURCE_DIR	Yes	Root directory for content files	/var/www/content
SITE_BASE_URL	Yes	Base URL for the site	https://example.com
OUTPUT_DIR	No (for URL gen)	Output directory for generated files	/var/www/public

Both SOURCE_DIR and SITE_BASE_URL are validated during URL generation. Missing values throw \RuntimeException:

Sources: src/Core/FileDiscovery.php231-234 src/Core/FileDiscovery.php258-262

---

URL Generation Testing

The codebase includes comprehensive tests for URL generation behavior, including edge cases and category routing logic.

Test Coverage

Test Suite	Focus	File Reference
FileDiscoveryFutureDateTest	Tests that future-dated files are filtered before URL generation	tests/Unit/Core/FileDiscoveryFutureDateTest.php
CategoriesServiceTest	Tests category name sanitization and output path categorization	tests/Unit/Features/Categories/Services/CategoriesServiceTest.php
MenuBuilderStaticMenusTest	Tests base URL prepending for static menu URLs	tests/Unit/Features/MenuBuilderStaticMenusTest.php
SearchIndexServiceTest	Tests URL calculation for search index entries	tests/Unit/Features/Search/SearchIndexServiceTest.php
RobotsTxtServiceTest	Tests web path calculation for robots.txt entries	tests/Unit/Features/RobotsTxt/RobotsTxtServiceTest.php

Sources: tests/Unit/Core/FileDiscoveryFutureDateTest.php tests/Unit/Features/Categories/Services/CategoriesServiceTest.php tests/Unit/Features/MenuBuilderStaticMenusTest.php tests/Unit/Features/Search/SearchIndexServiceTest.php tests/Unit/Features/RobotsTxt/RobotsTxtServiceTest.php

---

Summary

The URL generation system in StaticForge provides:

1. Deterministic URL creation from file paths during discovery phase
2. Category-based routing that organizes content by taxonomy
3. URL-safe slugification for special characters and spaces
4. Centralized storage in discovered_files for pipeline-wide access
5. Feature integration through standard URL consumption patterns

All URLs include the full SITE_BASE_URL, ensuring generated links work correctly regardless of hosting subdirectory or domain configuration. The separation between URL generation (discovery phase) and output path modification (render phase) allows features to operate independently while maintaining URL consistency.

Sources: src/Core/FileDiscovery.php13-296 src/Features/Categories/Feature.php1-92