Tuesday October 25, 2005 Customizing Maven 2 Site Layout
I consider the release of Maven 2 to be both good news and bad news. The good news is that it is just very good stuff. It's fast. It's simple. It's just so much better than Maven 1. The bad news is that I had done a lot of work in Maven 1, which I now need to port to Maven 2; I can no longer hide behind the fact that Maven 2 has not been released...
One of the things that I have on the roadmap for porting it to Maven 2 is a customization of the site rendering mechanism. This allowed us to have a Sun branded site layout, like shown below. The old mechanism was based on something calle JSL - a Jelly based implementation of XSLT. If you ever feel the urge to use JSL, then I suggest that you get control of yourself and resist the urge, because it is really awkward. (As well as interesting, from a hacker perspective.)
Today I started working on a way to achieve the same in Maven 2. This is what I've learned so far:
Howto
The site rendering mechanism in Maven 2 is no longer based on JSL, but on a combination of Velocity and Doxia. Velocity is - well I guess you all know Velocity. Doxia is the mechanism used for rendering the reports and transforming documents between different formats. If you want to change the site layout, then you should - at this stage - not be worried about Doxia. Doxia will become relevant if you want to generate reports yourself, or if you want to change the HTML of the reports being generated.
SiteMojo
The component responsible for rendering the site in Maven 2 is the SiteMojo component. This component accepts a number of properties to customize its behaviour. At this stage, there are two customiziation properties you should know about. The first one is the template property. This property allows you to set the name of the Velocity template containing all of the required templates and macros. By default, it will refer to a template file called "maven-site.vm".
The maven-site.vm file is included as a resource in the Maven 2 Site plugin. (Or stated otherwise, distributed as a resource included in the same jar as the SiteMojo class itself.) Overriding the template property on the SiteMojo will still result in the Mojo trying to resolve the template using the classloader mechanism. If you want to change that, then you should also modify the templateDirectory property.
Getting Started
I dediced to start this excercise by copying the maven-site.vm template from the Maven sources to a new directory (/home/wilfred/workspace/maven-template/). After that, I change the pom.xml file at the top of my project to include these lines:
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<configuration>
<templateDirectory>file:///home/wilfred/workspace/maven-template/</templateDirectory>
<template>maven-site.vm</template>
</configuration>
</plugin>
</plugins>
</build>
After a test run (mvn clean:clean site) it appears that the site is getting rendered correctly, without getting a different layout of course. Note that the templateDirectory property is set to an absolute URL. I haven't been able to address something relative to the ${basedir} - but then again, it is questionable if you would want that at all.
The hard part
As soon as you have your own maven-site.vm template, you can basically start to modify that template and examine the results after running mvn site.