Add ConfigTool for unified site configuration management

[bertysentry]

Add ConfigTool for Unified Site Configuration Management

Overview

This PR introduces a new ConfigTool that provides unified configuration management for Maven sites, merging site-wide settings from site.xml with per-page overrides from Markdown front matter.

Problem

Previously, handling configuration with front matter overrides required verbose manual code in Velocity templates for each variable:

#set($interpolation = $site.getCustomValue("interpolation", "maven"))
#set($tempHeadElement = $htmlTool.parseContent($headContent))
#if($tempHeadElement)
    #set($pageInterpolation = $htmlTool.getAttr($tempHeadElement, "meta[name=interpolation]", "content"))
    #if($pageInterpolation && !$pageInterpolation.isEmpty())
        #set($interpolation = $pageInterpolation.get(0))
    #end
#end

This pattern needed to be repeated for every configuration variable, making the code verbose and error-prone.

Solution

The new ConfigTool provides a clean, type-safe API:

#set($interpolation = $configTool.getValue($site, $headContent, "interpolation", "maven"))
#set($showToc = $configTool.getBooleanValue($site, $headContent, "showToc", true))
#set($tocMaxDepth = $configTool.getIntValue($site, $headContent, "tocMaxDepth", 3))

Features

Configuration Precedence

1. Front matter (per-page) - highest priority
2. Site-wide configuration (site.xml)
3. Default value - specified in the method call

API Methods

• getValue() - Get string configuration values
• getBooleanValue() - Get boolean values with intelligent parsing
  • Recognizes "true", "yes", "1" as true (case-insensitive)
  • Recognizes "false", "no", "0" as false (case-insensitive)
• getIntValue() - Get integer values with proper error handling

Technical Highlights

• ✅ Weak reference caching to avoid re-parsing headContent multiple times
• ✅ Reflection-based site model access (compatible with Maven Site Plugin 3.x and 4.x)
• ✅ Null-safe handling of all inputs
• ✅ Comprehensive error handling with sensible defaults

Testing

• 31 new unit tests covering all functionality
• Tests for precedence order, type conversion, null safety, caching, and edge cases
• All 108 tests pass (including existing tests)

Code Quality

• ✅ Checkstyle: 0 violations
• ✅ PMD: 0 violations
• ✅ SpotBugs: 0 bugs
• ✅ Javadoc: Complete and valid
• ✅ Code formatting: Compliant
• ✅ License headers: Present

Documentation

Updated src/site/markdown/index.md with:

• Usage examples
• Configuration precedence explanation
• Front matter and site.xml examples

Files Changed

• ✨ New: src/main/java/org/sentrysoftware/maven/skin/ConfigTool.java
• ✨ New: src/test/java/org/sentrysoftware/maven/skin/ConfigToolTest.java
• 📝 Modified: src/main/resources/tools.xml (registered $configTool)
• 📝 Modified: src/site/markdown/index.md (added documentation)

Usage Example

Markdown Front Matter

---
interpolation: none
showToc: false
tocMaxDepth: 2
---

# My Page

Content here...

Site-wide Configuration (site.xml)

<project>
  <custom>
    <interpolation>maven</interpolation>
    <showToc>true</showToc>
    <tocMaxDepth>3</tocMaxDepth>
  </custom>
</project>

Velocity Template Usage

#set($interpolation = $configTool.getValue($site, $headContent, "interpolation", "maven"))
#set($showToc = $configTool.getBooleanValue($site, $headContent, "showToc", true))
#set($tocMaxDepth = $configTool.getIntValue($site, $headContent, "tocMaxDepth", 3))

#if($showToc)
  <!-- Render table of contents with max depth $tocMaxDepth -->
#end

Closes

Fixes #103

[Copilot]

Pull request overview

Introduces a new Velocity ConfigTool to centralize configuration lookup for Maven sites, applying the precedence order of per-page front matter overrides (via <meta> tags) over site.xml <custom> values, with call-site defaults as fallback.

Changes:

• Added ConfigTool with getValue, getBooleanValue, and getIntValue helpers plus a headContent meta-tag parsing cache.
• Registered $configTool in tools.xml for application-scope use in Velocity templates.
• Added unit tests and updated site documentation with usage and precedence examples.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
src/main/java/org/sentrysoftware/maven/skin/ConfigTool.java	New tool implementing merged config lookup and caching for meta tags.
src/test/java/org/sentrysoftware/maven/skin/ConfigToolTest.java	New unit tests covering precedence and type conversion scenarios.
src/main/resources/tools.xml	Registers the new tool as configTool in the application toolbox.
src/site/markdown/index.md	Documents the new tool’s API, precedence rules, and examples.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.