Generating a project site with Maven

Maven can be used to generate a web site for your project.  This is done using the maven site plugin.  An Introduction to maven site generation can be found at http://www.sonatype.com/book/site-generation.html

There are two steps to the process: (1) generate the site, (2) deploy the site.

A basic site can be generated with the following command:

mvn site:site

The site will be created in the target/site diretory.  It is a good idea to view the generated site to verify that it looks ok before deploying.  The site plugin uses the plugins listed in the reporting section of the pom to determine some of the automatically generated information.

For example, to include javadocs in the maven site, the javadoc plugin can be included in the pom similar to the following:

  <reporting>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.2</version>
        <configuration>
          <links>
            <link>http://java.sun.com/j2se/1.5.0/docs/api</link>
          </links>
        </configuration>
      </plugin>
    </plugins>
  </reporting>

The second step is to deploy the generated site to a server where it is accessible from the Internet.

This is done using the deploy goal of the maven site plugin.

mvn site:deploy

This goal simply copies the generated site to the location specified in the "site" section of the distributionManagement section of the pom.  For example the jboss-retro project has the following site configuration:

    <site>
      <id>www.jboss.org</id>
      <name>www.jboss.org</name>
      <!-- This should be set to a local checkout of the jboss.org/jbossretro freezone. -->
      <url>file://${jbossretro.site.root}</url>
    </site>

The variable "jbossretro.site.root" can be configured in the settings.xml or on the command line.

Integration with JBoss.org

Each JBoss.org project has its content contained in subversion under this location:

https://cms.labs.jboss.com/prod/forge/portal-content/default/members/

The first step is to check out your project site, or if there is no site for your project, you can make a request for a new one from the jboss.org team.  After your basic project site has been created, check it out from svn.

The maven integration uses a feature of JBoss.org called "freezone" which is basically a way to host content as is.  Meaning without any additional markup.  There will be a subdirectory of the project checkout called "freezone", and this is where you can deploy your maven generated site.  Since by default maven creates a site with an apache configured look and feel, it is recommended to use a specialized skin for the site.

The skin can be configured in the file called "site.xml" which should be located in the directory src/site.

<project name="JBoss Retro">
  <skin>
    <groupId>org.jboss.maven.skins</groupId>
    <artifactId>maven-body-only-skin</artifactId>
  </skin>
</project>

This skin will remove all the apache content (heading, menus, etc) of the generated site, and keep only the main body of the reports.  More information about configuring the site descriptor can be found here

After configuring the skin, you can generate the site using

mvn site:site

.  When you view the html files, they will contain very little formatting information.  Next, check that the url in the site configuration points to the location of the local checkout of the freezone directory.

    <site>
      <id>www.jboss.org</id>
      <name>www.jboss.org</name>
      <!-- This should be set to a local checkout of the project freezone. -->
      <url>file://${path.to.project.freezone}</url>
    </site>

Now you can run

mvn site:deploy

and the generated site will be copied to the freezone directory.  Next, commit the files to svn, and the new content will appear on the jboss.org site within about 10 minutes.

For information about how to add content to the site, like project description, usage, etc. please refer to the

maven book

Note: work is currently in progress to improved the integration between the maven generated site and jboss.org so that the skin configuration will not be necessary.

Some examples of maven generated sites on jboss.org

http://labs.jboss.com/maven-jboss-deploy-plugin

http://labs.jboss.com/maven-jdocbook-plugin

http://labs.jboss.com/jbossretro

Referenced by: