- 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.
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.7.00</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 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