- User Documentation Getting Started
- Project Documentation Project Information 9 Project Reports 10
Getting Started
This artifact contains a collection of Velocity tools that are used by the Sentry Maven Skin.
Requirements
Maven must run on JDK 17 or later to use Maven Skin Tools.
This artifact must be loaded as a dependency by the Maven Site plugin, as below:
<plugin>
<artifactId>maven-site-plugin</artifactId>
<dependencies>
<dependency>
<groupId>org.sentrysoftware.maven</groupId>
<artifactId>maven-skin-tools</artifactId>
<version>1.8.01</version>
</dependency>
</dependencies>
</plugin>
This allows the Maven Skin and Velocity-processed pages in a Maven Site to invoke the below Velocity tools:
| Tool | Description | Javadoc |
|---|---|---|
$configTool |
To manage site configuration with front matter overrides | ConfigTool |
$htmlTool |
To manipulate HTML documents or fragments | HtmlTool |
$imageTool |
To manipulate images | ImageTool |
$indexTool |
To create search indexes | IndexTool |
$aiIndexTool |
To create AI-ready Markdown files from HTML documentation | AIIndexTool |
The AI-ready Markdown converter preserves the document's machine-readable structure. Sentry Maven Skin callouts remain blockquotes, interactive tabs become linear headings, table pipes and technical quotes remain literal data, table of contents links use the same anchors as Markdown headings, and print-only link footnotes are omitted.
The above tools are designed to be used only in the Velocity template of a Maven Site Skin as in the example below:
#set($bodyElement = $htmlTool.parseContent($bodyContent))
#set($bodyElement = $imageTool.explicitImageSize($bodyElement, "img", ${project.reporting.outputDirectory}, $currentFileName))
<html>
<body>
$bodyElement.html()
</body>
</html>
ConfigTool Usage
The ConfigTool provides unified configuration management, merging site-wide settings from site.xml with per-page overrides from Markdown front matter:
<!-- In your Velocity skin template -->
#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
Configuration precedence (highest to lowest):
- Front matter in Markdown files (converted to
<meta>tags by Doxia) - Site-wide configuration in
site.xmlunder<custom>element - Default value specified in the method call
Example front matter in a Markdown page:
---
interpolation: none
showToc: false
tocMaxDepth: 2
---
# My Page Title
Content goes here...
Example site-wide configuration in site.xml:
<project>
<custom>
<interpolation>maven</interpolation>
<showToc>true</showToc>
<tocMaxDepth>3</tocMaxDepth>
</custom>
</project>
Additionally, we allow the use of these standard Velocity tools in the Velocity-processed pages (e.g. in src/site/markdown/*.md.vm):
| Tool | Description | Javadoc |
|---|---|---|
$collection |
Tool gathering several collection utilities | CollectionTool |
$json |
Tool for JSON parsing and rendering | JsonTool |
$log |
Tool to trigger logs from withing templates | LogTool |
Example:
#set( $repoList = $json.fetch("https://api.github.com/orgs/sentrysoftware/repos") )
#if( $repoList && $repoList.size() > 0 )
| Repository | Description |
|------------|-------------|
#foreach ($repo in $repoList.iterator() )
| $repo.name | $!repo.description |
#end
#else
$log.error("Could not fetch repositories")
*No repositories.*
#end