writing a maven doxia site renderer plugin

Things can be so simple and yet so hard to figure out. As part of the staticwiki project, I wanted to have a maven plugin where the staticwiki engine could be used to write pages which are included in the maven site generation.

This is handled in maven by doxia, the tool which generates the site. As many other parts of maven, it is rather poorly documented how you can extend this. However, after a lot of searching and trial and error, it finally worked.

The base principle is quite simple. You basically have to implement two interfaces which are wired into maven thanks to the plexus container. You don’t even have to write any wiring code as this is done partly by a plugin and some annotations, and partly automatically.

  • You need to implement a SiteModule to make sure doxia knows where the files can be found and in which extension. A short example can be found (from staticwiki) can be found here. Note especially the plexus.component annotation-comment which is used to generate the plexus mapping file.
  • You also need to implement a doxia Parser. This parses the input file and then generates the output using doxia, specifically using the Sink object. Fortunately (for us) it can just be passed some html. A simple example (the actual parsing is in a seperate class) can be found here. Again note the plexus.component annotation-comment.
  • Lastly you have to tie everything together, using the build tools to produce the plexus component descriptor. As you can see here, you need to include the plexus-maven-plugin.

The most difficult part to figure out is how to assure the new renderer is used when actually generating the site. It seems there are many options, including as build plugin, reporting plugin or build extension. Neither of these work. The only way I have found to work is to explicitly include the maven-site-plugin and include your own renderer in the dependencies section for that.

<build>
...
<plugins>
...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<dependencies>
<dependency>
<groupId>org.staticwiki</groupId>
<artifactId>staticwiki-site-plugin</artifactId>
<version>1.0-SNAPSHOT</version>
<    /dependency>
</dependencies>
</plugin>
...
</plugins>
...
<build>

Leave a Reply

Your email address will not be published. Required fields are marked *

question razz sad evil exclaim smile redface biggrin surprised eek confused cool lol mad twisted rolleyes wink idea arrow neutral cry mrgreen

*