Architecture

How site.vm Works

The Velocity template src/main/resources/META-INF/maven/site.vm is the core of StILi. It renders every Maven page in the following structure:

<h1 id="stili-title">Page Title</h1>
<div id="stili-body">
  $bodyContent
</div>

A JSON metadata block is appended after the body:

<script id="stili-json" type="application/json">
{
  "project": "Project Name",
  "groupId": "de.juplo",
  "artifactId": "my-project",
  "version": "1.0.0",
  "pages": [ ... ]
}
</script>

This block is the machine-readable interface between StILi and the import scripts.

The stili-json Format

The top-level fields mirror the Maven project coordinates:

Field Source
project Display name from POM <name>
groupId POM <groupId>
artifactId POM <artifactId>
version POM <version>
generator Maven Doxia Site Renderer version
generated ISO-8601 timestamp of generation
pages Array of all pages (see below)

The pages Array

The pages array contains every page of the Maven site in the order they appear in the configured navigation menu. The array position serves as the weight for sorting of the entries in the navigation of the target system.

Each entry looks like the following example:

{
  "name": "Plugins",
  "href": "plugins.html",
  "childs": [      ],
  "crumbs": [
    "project-info.html"      ],
  "path": "project-info/"
}
Field Meaning
name Display name of the page
href Filename relative to the site root (e.g. project-reports.html; for generated directories e.g. apidocs/index.html)
childs Direct children in the menu tree (their href values)
crumbs Ancestor pages of the page (their href values), beginning at the root of the project, but excluding index.html
path Ancestors of the page as a directory path — that is, the entries of crumbs concatenated and with .html replaced by /

Page Types

Type Example Detection
Root index.html href == "index.html"
Section node (has children) project-reports.html childs.length > 0
Leaf page configuration.html childs.length == 0
Generated content apidocs/, xref/ etc. Subdirectory, not an HTML file

Generated content (JavaDocs, cross-references, etc.) appears as a subdirectory in the Maven site output and has a pages entry with an href like apidocs/index.html.

Body Extraction

Import scripts can extract the page body from each HTML file using a pattern like this:

sed -n '/<script id="stili-json" type="application\/json">/q;p' "$SOURCE" \
  | tail -n +2
  • sed outputs all lines before the JSON block (and stops). For non-index.html files there is no JSON block, so all content is output.
  • tail -n +2 drops the first line (<h1 id="stili-title">...</h1>), leaving only the <div id="stili-body"> and its content.