Configuring the Site Descriptor

You can create your own site descriptor for your project when you want to override the navigation tree for the site. For example, aside from the generated reports you want to add additional content to your site. In order for it to be accessible in the generated site, you must configure your site descriptor. You create the site descriptor in a file called site.xml which should be located in your src/site directory.

If you are migrating from Maven 1.x you will be interested to know that the navigation.xml file has been replaced by the site descriptor in Maven 2. The format is nearly the same, so you can probably reuse most of your old file.

Title

The title of each generated page will be a combination of the site title and the title of the current page. By default the Site Plugin will use the value of ${project.name} from your pom.xml file as the site title. The complete title for this page is "Maven Site Plugin - Configuring the Site Descriptor".

If you want to use a different site title, but do not want to change the <name> element in your pom.xml , you can configure this in your site.xml , like this:

<project name="My Site Title">
  ...
</project>

Publish Date

With the out-of-the-box Velocity template, the position of the "Last Published" date is configurable. By default, the position is on the left but you can change it. To do this, you can add a <publishDate> element to your site.xml like the following:

<project>
  ...
  <publishDate position="navigation-bottom" format="MM-dd-yy"/>
  ...
</project>

The position attribute can have one of these values: left , right , navigation-top , navigation-bottom , bottom .

If you want hide the publish date, you can use this in your site.xml :

<project>
  ...
  <publishDate position="none"/>
  ...
</project>

"Powered by" Logo

You can add your own "Powered by" logo to your site. To do this, you add a <poweredBy> element in your site.xml like this:

<project>
  ...
  <poweredBy>
    <logo name="Maven" href="http://maven.apache.org/"
          img="http://maven.apache.org/images/logos/maven-feather.png"/>
  </poweredBy>
  ...
</project>

Inheritance

Site descriptors are inherited along the same lines as project descriptors are. When you deploy a project, its site descriptor is also deployed so that it can be inherited.

By default, only the basic settings are inherited. From the body, only the links are inherited, and these accumulate to contain all the parents' site descriptor links.

However, it is possible to inherit menus as well. To do so, use the inherit attribute in the site descriptor. This can be either top or bottom , indicating where in the menu it will be placed after inheritance. For example:

<project>
  ...
  <body>
    ...
    <menu name="My Inherited Menu" inherit="top">
      ...
    </menu>
    ...
  </body>
  ...
</project>

Including Generated Content

There are several preset menus that can be used in the site descriptor to include generated content from your project. These are:

  • reports - a menu with links to all the generated reports for your project
  • parent - a menu with a link to the parent project's site
  • modules - a menu containing the links to the sites of the submodules of this project

To include a preset menu, use the ref attribute. For example:

<project>
  ...
  <body>
    ...
    <menu ref="modules" />
    ...
  </body>
  ...
</project>

Note: The old syntax using ${reports} , ${parent} and ${modules} has been deprecated and you are encouraged to use the new syntax instead. The support for the old syntax will be removed in a future version of the Site Plugin.

Skinning

Skins can be created to customize the look and feel of a site in a consistent way. For more information on creating a skin, see Creating a Skin . To reference a skin in your project, you use the skin element of the site descriptor. This is a regular artifact or dependency-like element. For example, to use the Maven Classic Skin , you would include:

<project>
  ...
  <skin>
    <groupId>org.apache.maven.skins</groupId>
    <artifactId>maven-classic-skin</artifactId>
    <version>1.0</version>
  </skin>
  ...
</project>

Note: The <version> element is optional and, like plugins, if omitted the latest version available will be used.

This skin will copy the necessary resources including CSS and if necessary use the included alternate Velocity template to render the site.

Expressions

The site.xml can contain some expressions, like ${project.name} . Each expression will be evaluated when the site is rendered.

Expressions can be:

  • ${project.*}, for instance ${project.organization.name} referenced in <project><organization><name>
  • ${project.properties}, for instance ${myProperty} referenced in <project><properties><myProperty>
  • ${environmentVariable}, for instance ${JAVA_HOME}

Note: Support for some expressions, like ${project.name} is present in version 2.0-beta-5 of this plugin. Full support is only available since version 2.0-beta-6.