 |
VOOZH | about |
|
VOOZH | about |
This document covers how content is managed in StaticForge, including supported file formats, frontmatter metadata syntax, file discovery, and URL generation. For detailed information about specific aspects:
Content in StaticForge consists of text files stored in the SOURCE_DIR directory (default: content/). Each file contains two parts: frontmatter (YAML metadata) and content (Markdown or HTML). The FileDiscovery service scans these files, parses their metadata, generates URLs, applies filtering rules, and stores the results in the container for processing.
StaticForge processes two content file formats, both supporting YAML frontmatter:
| Format | Extension | Frontmatter Syntax | Content Type | Processed By |
|---|---|---|---|---|
| Markdown | .md | ---...--- | Markdown | MarkdownRenderer |
| HTML | .html | <!-- ---...--- --> | HTML | HtmlRenderer |
Diagram: Content File Structure
Sources:
The FileDiscovery class orchestrates content scanning and metadata extraction:
Diagram: FileDiscovery Workflow
Sources:
Directory Scanning: FileDiscovery uses RecursiveDirectoryIterator to traverse the directory tree starting from directories specified in SCAN_DIRECTORIES (or SOURCE_DIR as fallback) src/Core/FileDiscovery.php56-70
Extension Filtering: Each file is checked against the ExtensionRegistry to determine if it can be processed src/Core/FileDiscovery.php86
Frontmatter Parsing: Depending on file extension, either parseMarkdownFrontmatter() or parseHtmlFrontmatter() extracts YAML metadata using regex patterns src/Core/FileDiscovery.php162-192
Draft Filtering: Files with draft: true metadata are skipped unless SHOW_DRAFTS is enabled src/Core/FileDiscovery.php92-102
Future Date Filtering: Files with a date field containing a future timestamp are excluded from the build src/Core/FileDiscovery.php104-118
URL Generation: generateUrl() calculates the final URL for each file based on path, filename, and category metadata src/Core/FileDiscovery.php222-269
Storage: Discovered files are stored in the container as discovered_files, an array of file metadata src/Core/FileDiscovery.php46
After discovery, each file is represented in the discovered_files array with the following structure:
This structure is accessed by all features during the generation lifecycle, enabling features to:
Sources:
The following table lists standard frontmatter fields and their effects:
| Field | Type | Purpose | Example | Used By |
|---|---|---|---|---|
title | string | Page title | "My Post" | Templates, Search, Sitemap |
description | string | Page summary | "A guide to..." | Meta tags, RSS, Search |
category | string | Content categorization | "blog" | Categories feature, URL routing |
tags | array/string | Topic tags | ["php", "web"] | Tags feature, Search |
menu | string | Menu position | "1.5" or "2.1.3" | MenuBuilder |
date | string/int | Publication date | "2024-01-15" | Date filtering, RSS, Sorting |
draft | boolean | Draft status | true | FileDiscovery filtering |
template | string | Template override | "custom" | TemplateRenderer |
type | string | Content type | "category" | CategoryIndex, Special handling |
robots | string | Crawler control | "no" | RobotsTxt generation |
search_index | boolean | Search inclusion | false | Search feature |
Sources:
The generateUrl() method transforms source file paths into web URLs following these rules:
Diagram: URL Generation Flow
Sources:
Path Relativization: Strip SOURCE_DIR prefix from absolute path src/Core/FileDiscovery.php237
Extension Transformation: Replace .md or .html with .html using regex src/Core/FileDiscovery.php240
Category Routing: If category metadata exists, calculate category slug and insert as subdirectory src/Core/FileDiscovery.php242-255
Base URL Prepending: Add SITE_BASE_URL with proper slash handling src/Core/FileDiscovery.php258-268
For a file content/posts/article.md with category: "Web Development":
Source Path: content/posts/article.md
Relative Path: posts/article.md
Extension Change: posts/article.html
Category Applied: web-development/article.html
Final URL: https://example.com/web-development/article.html
The category slug is generated by slugify() which:
Sources:
Content files move through multiple processing stages after discovery:
Diagram: Content Processing Pipeline with Code References
Sources:
FileDiscovery scans directories and populates discovered_filesFeatures access content metadata throughout the lifecycle via the discovered_files array stored in the container.
Sources:
StaticForge provides multiple ways to control which content appears in builds:
Files with draft: true in frontmatter are excluded unless SHOW_DRAFTS environment variable is set:
Implementation: src/Core/FileDiscovery.php92-102
Files with date metadata containing a future timestamp are automatically excluded:
Implementation: src/Core/FileDiscovery.php104-118
Files can opt-out of search indexing via frontmatter or configuration:
Frontmatter exclusion:
Configuration exclusion in siteconfig.yaml:
Implementation: src/Features/Search/Services/SearchIndexService.php191-225
Pages marked with robots: no are added to the site's robots.txt disallow list:
Implementation: src/Features/RobotsTxt/Services/RobotsTxtService.php109-126
Sources:
The ExtensionRegistry service determines which file extensions can be processed. By default, .md and .html are registered. Features can register additional extensions during initialization.
Registration: Features register extensions by calling ExtensionRegistry::registerExtension() during their register() method.
Checking: FileDiscovery calls ExtensionRegistry::canProcess() for each file to determine if it should be included in the build.
Sources:
Content metadata drives behavior across multiple features:
| Feature | Metadata Used | Purpose |
|---|---|---|
| MenuBuilder | menu | Builds numbered and static navigation menus |
| Categories | category | Routes content to category subdirectories |
| CategoryIndex | type: category | Generates category landing pages |
| Tags | tags | Creates tag clouds and tag pages |
| Search | title, description, tags, search_index | Builds search index with page sections |
| RSSFeed | title, description, date, category | Generates RSS feed entries |
| Sitemap | All URLs | Creates sitemap.xml |
| RobotsTxt | robots | Controls crawler access |
| ChapterNav | menu | Generates prev/next navigation |
Sources:
Content management behavior is controlled by these container variables:
| Variable | Type | Purpose | Default |
|---|---|---|---|
SOURCE_DIR | string | Primary content directory | "content" |
SCAN_DIRECTORIES | array | Directories to scan for content | [SOURCE_DIR] |
SHOW_DRAFTS | boolean | Include draft files in build | false |
SITE_BASE_URL | string | Base URL prepended to all URLs | Required |
site_config | array | Parsed siteconfig.yaml | [] |
discovered_files | array | All discovered content files | [] |
Sources:
This content management system provides the foundation for StaticForge's file-based architecture. For detailed information on specific processing steps, consult the sub-pages listed at the beginning of this document.
Refresh this wiki