Navigation & Structure Features

This page documents the built-in features that organize content and generate navigation structures in StaticForge. These features work together during the POST_GLOB and POST_RENDER event phases to build menus, categorize content, create index pages, and provide sequential navigation.

For content rendering features (Markdown and HTML processing), see Content Renderers. For SEO and discovery features (sitemaps, RSS, robots.txt), see SEO & Discovery Features.

---

Feature Overview

The following table summarizes the navigation and structure features, their event priorities, and primary responsibilities:

Feature	Events	Priority	Purpose
CategoryIndex	POST_GLOB	50	Scans for category definitions and generates index pages
MenuBuilder	POST_GLOB	100	Builds navigation menus from content frontmatter
Tags	POST_GLOB	150	Extracts tags from content and generates tag clouds
Categories	POST_GLOB POST_RENDER	250 100	Applies category templates and restructures output paths
ChapterNav	POST_GLOB	200	Generates sequential (previous/next) navigation links

Sources: src/Core/FeatureManager.php1-391 content/development/architecture.md1-247

---

Navigation & Structure Architecture

The following diagram shows how navigation and structure features interact during the site generation pipeline:

Priority Execution Order:

1. CategoryIndex (50) runs first to create category index pages so they exist before menu generation
2. MenuBuilder (100) scans all files and builds menu structures
3. Tags (150) extracts tag metadata and generates tag cloud HTML
4. ChapterNav (200) builds sequential navigation for numbered menus
5. Categories (250) applies category-specific templates to content files

This ordering ensures that category pages exist before they're added to menus, and that templates are applied after initial structure is established.

Sources: src/Core/FeatureManager.php1-391 src/Features/Categories/Feature.php1-93 content/development/architecture.md63-154

---

MenuBuilder Feature

The MenuBuilder feature generates navigation menus from content frontmatter. It supports two distinct menu systems: numbered menus (content-driven) and named menus (static).

Menu System Architecture

Sources: content/features/menu-builder.md1-215 content/guide/site-config.md32-109

Numbered Menu Positioning System

Numbered menus use a dot-notation system where menu: X.Y.Z means:

• X: Menu number (1, 2, 3, etc.)
• Y: Position within menu (1.0, 1.5, 2.0, etc.)
• Z: Dropdown position (0 = dropdown title, 1+ = dropdown items)

Frontmatter Examples:

Creates the first item in menu 1.

Creates a dropdown title at position 3 in menu 1.

Creates the first item inside the "Services" dropdown.

Multi-Menu Placement:

Places the same page in menu 1 (position 5) and menu 2 (position 3).

Sources: content/features/menu-builder.md36-122

MenuBuilder Event Lifecycle

The MenuBuilder processes menus during POST_GLOB at priority 100. This allows category index pages (created at priority 50) to be included in menus.

Sources: content/features/menu-builder.md189-202 content/development/architecture.md106-128

Template Access

Pre-rendered HTML (recommended):

Manual iteration (custom markup):

Menu data structure (accessed via features.MenuBuilder.files[X]):

Property	Type	Description
title	string	Page title (from frontmatter or H1)
url	string	Generated URL with category prefix
file	string	Source file path
position	string	Menu position (e.g., "1.2")

Sources: content/features/menu-builder.md123-188

---

Categories Feature

The Categories feature organizes content into category subdirectories and applies category-specific templates. It operates in two phases: template application (POST_GLOB) and path restructuring (POST_RENDER).

Category URL Transformation

The Categories feature modifies output_path during POST_RENDER to inject the category subdirectory. If a file has category: tech, the output path changes from output/my-post.html to output/tech/my-post.html.

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

Category Template Application

During POST_GLOB (priority 250), Categories scans for category definition files with type: category in their frontmatter:

Category Definition File (content/categories/tech.md):

The CategoriesService extracts the template and applies it to all files with category: tech (unless they explicitly specify a different template).

Processing Flow:

Sources: src/Features/Categories/Services/CategoriesService.php22-103

Category Name Sanitization

Category names in frontmatter are sanitized for filesystem paths:

Input Category	Sanitized Slug
Tech	tech
Web Dev	web-dev
C#	c
Multiple Spaces	multiple-spaces

The sanitization logic: src/Features/Categories/Services/CategoriesService.php136-148

Algorithm:

1. Convert to lowercase
2. Replace non-alphanumeric characters with hyphens
3. Trim leading/trailing hyphens

Sources: tests/Unit/Features/Categories/Services/CategoriesServiceTest.php25-32

---

CategoryIndex Feature

The CategoryIndex feature generates index pages for categories, displaying all articles within each category with thumbnails and metadata.

Category Data Collection

Sources: src/Features/CategoryIndex/Services/CategoryService.php25-134

Image Extraction for Category Cards

The ImageService extracts hero images for category index cards using a priority fallback:

1. Frontmatter hero field: hero: assets/images/my-hero.jpg
2. Frontmatter social.image field: social: { image: "assets/images/og.jpg" }
3. Frontmatter image field: image: assets/images/cover.jpg
4. First <img> in HTML: Scraped from rendered content

If a local image is found, the ImageService generates a thumbnail (300x200px, JPEG, 85% quality) using ImageMagick:

Thumbnails are cached in public/images/ with the filename {content-filename}.jpg.

Sources: src/Features/CategoryIndex/Services/ImageService.php24-111

Category Model Structure

The Category class stores category metadata and associated files:

Property	Type	Description
slug	string	Sanitized category name (e.g., "web-dev")
title	string	Display title from metadata
description	string	Category description
template	string	Template to apply to category articles
files	CategoryFile[]	Array of files in this category

Each CategoryFile contains:

Property	Type	Description
title	string	Article title
url	string	Relative URL (e.g., "/tech/article.html")
date	string	Publication date (YYYY-MM-DD)
image	string|null	Thumbnail URL
metadata	array	Full frontmatter array

Sources: src/Features/CategoryIndex/Services/CategoryService.php1-134

---

ChapterNav Feature

The ChapterNav feature generates sequential navigation (previous/next links) for numbered menus. It's commonly used for documentation sites or tutorial series.

Configuration

ChapterNav is configured in siteconfig.yaml:

Fallback: If not in siteconfig.yaml, ChapterNav checks these environment variables:

• CHAPTER_NAV_MENUS
• CHAPTER_NAV_PREV_SYMBOL
• CHAPTER_NAV_NEXT_SYMBOL
• CHAPTER_NAV_SEPARATOR

Sources: content/guide/site-config.md193-224

Sequential Navigation Generation

ChapterNav processes numbered menus during POST_GLOB at priority 200, after MenuBuilder (100) has created the menu structures.

Generated HTML structure:

The navigation HTML is stored in the Container as chapter_nav and accessed in templates:

Sources: content/guide/site-config.md193-224

---

Tags Feature

The Tags feature extracts tag metadata from content frontmatter and generates tag cloud HTML during the POST_GLOB phase (priority 150).

Tag Extraction

Tags are defined in content frontmatter as an array or comma-separated string:

or

Tag Cloud Generation

The Tags feature builds a tag cloud with frequency-based sizing. The generated HTML is stored in the Container at features.Tags.cloud.

Template access:

Expected HTML output:

Tag cloud CSS classes (e.g., tag-size-1 through tag-size-5) can be styled to vary font size based on frequency.

Sources: content/guide/configuration.md415-423

---

Feature Integration Patterns

The navigation and structure features are designed to work together through shared Container data and event ordering:

Dependency Chain

Key Integration Points:

1. CategoryIndex → MenuBuilder: Category index pages must exist before MenuBuilder runs so they can be included in menus
2. MenuBuilder → ChapterNav: ChapterNav requires complete menu structures to generate sequential navigation
3. All → Categories: Categories runs last (priority 250) to apply templates after all structural decisions are made

Sources: content/development/architecture.md106-128

Container Data Flow

All features store their output in the Container for template access:

Feature	Container Variable	Type	Template Access
MenuBuilder	menu1, menu2, etc.	HTML string	{{ menu1|raw }}
MenuBuilder	menu_top, menu_footer	HTML string	{{ menu_top|raw }}
MenuBuilder	features.MenuBuilder.files[X]	array	features.MenuBuilder.files[1]
Categories	category_templates	array	Internal use only
CategoryIndex	features.CategoryIndex.categories	Category[]	Template iteration
Tags	features.Tags.cloud	HTML string	{{ features.Tags.cloud|raw }}
ChapterNav	chapter_nav	HTML string	{{ chapter_nav|raw }}

Sources: content/development/templates.md86-91 content/features/menu-builder.md123-188

---

Configuration Reference

Frontmatter Fields

Field	Type	Used By	Purpose
menu	string/array	MenuBuilder	Menu position(s): 1.2 or 1.2, 2.3
category	string	Categories, CategoryIndex	Category assignment: tech, blog
type	string	CategoryIndex	Mark as category definition: category
template	string	Categories	Template override for content
tags	array/string	Tags	Tag assignment: ["php", "web"]
hero	string	CategoryIndex	Hero image path
image	string	CategoryIndex	Fallback image path

siteconfig.yaml

Named Menus:

Chapter Navigation:

Feature Disabling:

Sources: content/guide/site-config.md32-264

---

Event Priority Summary

The following table shows the complete event lifecycle for navigation and structure features:

Phase	Event	Feature	Priority	Action
Planning	POST_GLOB	CategoryIndex	50	Scan category definitions, create index pages
Planning	POST_GLOB	MenuBuilder	100	Build menu structures from frontmatter
Planning	POST_GLOB	Tags	150	Extract tags, generate tag cloud
Planning	POST_GLOB	ChapterNav	200	Generate sequential navigation
Planning	POST_GLOB	Categories	250	Apply category templates to content
Processing	POST_RENDER	Categories	100	Modify output paths to include category subdirs

Why this order matters:

• CategoryIndex runs first to ensure category pages exist
• MenuBuilder runs second to include category pages in menus
• Categories runs last in POST_GLOB to apply templates after structure is decided
• Categories runs in POST_RENDER to restructure paths after content is rendered

Sources: content/development/architecture.md106-128 src/Features/Categories/Feature.php25-28