One awesome plugin, in the great variety of plugins that come with maven, is the site plugin. Its goal is to automatically generate a website based on content provided by the user. This website is enriched with automatically generated documentation.

An elementary part of the site plugin is the site.xml file. This file has to be stored in project/src/site. It includes all additional contents to be added to the project site and describes the layout of the site. Maven organizes the actual contents by format. The user has to ensure that custom files are stored in a special format. Maven supports XML and APT among others. When it generates the site, the contents are converted to HTML.

On http://maven.apache.org/plugins/maven-site-plugin/examples/sitedescriptor.html
you will find detailed information on how to configure the site descriptor.

The MD-format

MD stands for “markdown”. It strives for simplicity and therefore is a format that users will learn intuitively. For more information, visit http://daringfireball.net/projects/markdown/.

Luckily, the site plugin now parses Markdown files as well.

Auto generated content by plugins

One section of the pom.xml is devoted to the plugins embedded into the project. The following table gives an overview about various plugins generating sections on the website.

ArtifactID Type Description Link
maven-license-plugin build plugin Updates license headers of source files http://code.google.com/p/maven-license-plugin/
maven-project-info-reports-plugin reporting plugin Responsible for displaying information about continuous integration, dependencies, etc. http://maven.apache.org/plugins/maven-project-info-reports-plugin/
maven-dependency-plugin build plugin Provides the capability to manipulate artifacts http://maven.apache.org/plugins/maven-dependency-plugin/
maven-javadoc-plugin reporting plugin Uses the Javadoc tool to generate javadocs for the specified project http://maven.apache.org/plugins/maven-javadoc-plugin/
maven-jxr-plugin build plugin Produces cross-references of the project’s sources http://maven.apache.org/plugins/maven-jxr-plugin/
maven-surefire-report-plugin reporting plugin Parses the generated TEST-*.xml files under ${basedir}/target/surefire-reports and renders them to DOXIA creating the web interface version of the test results http://maven.apache.org/plugins/maven-surefire-report-plugin/
cobertura-maven-plugin build plugin Shows output of Cobertura http://mojo.codehaus.org/cobertura-maven-plugin/
maven-checkstyle-plugin reporting plugin Generates a report regarding checkstyle http://maven.apache.org/plugins/maven-checkstyle-plugin/
maven-pmd-plugin reporting plugin Generating a site report with PMD results http://maven.apache.org/plugins/maven-pmd-plugin/
maven-compiler-plugin build plugin Used to compile the sources of your project http://maven.apache.org/plugins/maven-compiler-plugin/
maven-assembly-plugin build plugin Primarily intended to allow users to aggregate the project output along with its dependencies, modules, site documentation, and other files into a single distributable archive. http://maven.apache.org/plugins/maven-assembly-plugin/
maven-source-plugin build plugin Creates a jar archive of the source files http://maven.apache.org/plugins/maven-source-plugin/
maven-site-plugin reporting plugin Responsible for generating and deploying the project site http://maven.apache.org/plugins/maven-site-plugin/
maven-acr-plugin build plugin This plugin generates J2EE Application Client files http://maven.apache.org/plugins/maven-acr-plugin/
maven-antrun-plugin build plugin Provides the ability to run Ant tasks within Maven 2 http://maven.apache.org/plugins/maven-antrun-plugin/
maven-changelog-plugin reporting plugin Generates reports regarding recent changes in your SCM http://maven.apache.org/plugins/maven-changelog-plugin/
maven-clean-plugin build plugin Used when you want to remove files generated at build-time in a project’s directory http://maven.apache.org/plugins/maven-clean-plugin/
maven-deploy-plugin build plugin Primarily used during the deploy phase, to add your artifact(s) to a remote repository for sharing with other developers and projects http://maven.apache.org/plugins/maven-deploy-plugin/
maven-eclipse-plugin build plugin Used to generate Eclipse IDE files (*.classpath, *.wtpmodules and the .settings folder) for use with a project http://maven.apache.org/plugins/maven-eclipse-plugin/
maven-enforcer-plugin reporting plugin Provides goals to control certain environmental constraints such as Maven version, JDK version and OS family along with many more standard rules and user created rules http://maven.apache.org/plugins/maven-enforcer-plugin/
maven-failsafe-plugin build plugin Designed to run integration tests while the Surefire Plugins is designed to run unit tests http://maven.apache.org/plugins/maven-failsafe-plugin/
maven-help-plugin reporting plugin Used to get relative information about a project or the system or particular plugins http://maven.apache.org/plugins/maven-help-plugin/
maven-install-plugin build plugin Used during the install phase to add artifact(s) to the local repository http://maven.apache.org/plugins/maven-install-plugin/
maven-invoker-plugin reporting plugin Runs a set of Maven projects http://maven.apache.org/plugins/maven-invoker-plugin/
maven-jar-plugin build plugin Provides the capability to build and sign jars http://maven.apache.org/plugins/maven-jar-plugin/
maven-patch-plugin build plugin Used to apply patches to source files http://maven.apache.org/plugins/maven-patch-plugin/
maven-pdf-plugin reporting plugin Allows you to generate a PDF version of your project’s documentation http://maven.apache.org/plugins/maven-pdf-plugin/
maven-plugin-plugin build plugin Creates a Maven plugin descriptor for any mojos found in the source tree to be included in the JAR http://maven.apache.org/plugins/maven-plugin-plugin/
maven-release-plugin build plugin Releases a project with Maven, saving a lot of repetitive, manual work http://maven.apache.org/plugins/maven-release-plugin/
maven-repository-plugin build plugin Creates bundles of artifacts that can be uploaded to the central repository http://maven.apache.org/plugins/maven-repository-plugin/
maven-resources-plugin build plugin Handles the copying of project resources to the output directory http://maven.apache.org/plugins/maven-resources-plugin/
maven-stage-plugin build plugin Copies artifacts from one repository to another http://maven.apache.org/plugins/maven-stage-plugin/
maven-surefire-plugin build plugin Used during the test phase of the build lifecycle to execute the unit tests of an application http://maven.apache.org/plugins/maven-surefire-plugin/
maven-toolchain-plugin build plugin Shares configuration across plugins. Makes for example sure the plugins like compiler, surefire, javadoc, webstart etc. all use the same JDK for execution http://maven.apache.org/plugins/maven-toolchains-plugin/
maven-war-plugin build plugin Responsible for collecting all artifact dependencies, classes and resources of the web application and packaging them into a web application archive http://maven.apache.org/plugins/maven-war-plugin/
doxia-module-markdown build plugin Supports markdown formate for site generation https://bitbucket.org/nicoulaj/doxia-module-markdown

Configuring the site-deploy

Having generated your project site with the help of site plugin, you’ll probably want to deploy it somewhere. This can be accomplished either locally (in $project_basedir/target/site) or on a remote server. In the latter case, you’ll have to decide which protocol you want to use to upload the site. Usually, this would be FTP or FTPs. Due to a buggy wagons, it currently is SSH.

  • Assuming you want to store your project site on a remote server, you’ll need to add the project site to the distribution management of your pom.xml:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
   <modelVersion>4.0.0</modelVersion>
   <distributionManagement>
      <site>
         <id>perfidix</id>
         <url>ftp://web.uni-konstanz.de/html/</url>
      </site>
   </distributionManagement>

1st note: In case you should want to deploy your site with FTP over SSL, the url has to be ftp://... instead of ftps://...
2nd note: Until further notice, the distributionManagement section contains the following info:

<distributionManagement>
   <site>
      <id>sf</id>
      <url>scp://shell.sf.net/home/project-web/perfidix/htdocs/</url>
      <!-- <url>sftp://web.sf.net/home/project-web/perfidix/htdocs/</url> -->
      <!-- <id>perfidix-rz</id> <url>sftp://web.uni-konstanz.de/html</url> -->
   </site>
</distributionManagement>
  • Next, you’ll need to edit the extensions section of the pom to implement the wagon uploading the site.
<extensions>
   <extension>
      <groupId>org.apache.maven.wagon</groupId>
      <artifactId>wagon-ftp</artifactId>
      <version>2.0</version>
   </extension>
   <extension>
      <groupId>org.apache.maven.wagon</groupId>
      <artifactId> wagon-ssh</artifactId>
      <version>2.0</version>
   </extension>
</extensions>
  • Now that the adjustments of the pom.xml are complete, you’ll need to add your credentials for your project site to $user's_homedir/.m2/settings.xml.
<settings xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<servers>
   <server>
      <id> </id>
      <username> </username>
      <password> </password>
   </server>
</servers>
  • You are now able to deploy your project site with
mvn site:deploy

Site Generation for Multi Module Projects

Generating a multi module project site locally will work at first sight. Taking a closer look, you will discover that the relative links don’t work properly. This is fixed with a successful site:deploy.

If you want to make sure that the site works properly before deploying it, site:stage is the solution. For this, you need to add the distributionManagement section as well as project-wide required plugins and dependencies only to the parent pom. After that, site:stage will provide a local version of the project site in a subdirectory of $project_basedir/src/staging which is named either after the server it’s going to be deployed to or as “complete”.

Generation of Project Reports

Treetank’s root site contains all project-wide information such as license, project team, etc. Selective reports can be generated by adding the desired reports to the project-info-reports-plugin of the root POM.

<plugins>
  <plugin>
    <artifactId>maven-site-plugin</artifactId>
    <version>3.0</version>
    <configuration>
      <reportPlugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-project-info-reports-plugin</artifactId>
          <version>2.2</version>
          <configuration>
            <dependencyDetailsEnabled>false</dependencyDetailsEnabled>
             <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
          </configuration>
          <reports>
              <report>index</report>
              <report>project-team</report>
              <report>modules</report>
              <report>dependency-convergence</report>
              <report>cim</report>
              <report>issue-tracking</report>
              <report>license</report>
              <report>scm</report>
              <report>summary</report>
          </reports>
        </plugin>
      </reportPlugins>
    </configuration>
    <dependencies>
      <dependency>
        <groupId>org.apache.maven.doxia</groupId>
        <artifactId>doxia-module-markdown</artifactId>
        <version>1.3-SNAPSHOT</version>
      </dependency>
    </dependencies>
  </plugin>
</plugins>

Inherited or module specific plugins such as maven-pmd-plugin must be added to the plugin section of the corresponding POMs. To display the project reports, the menus in the site.xml files must be set to reports:

<menu ref="reports"/>