Apache Maven 1.x has reached its end of life, and is no longer supported. For more information, see the announcement. Users are encouraged to migrate to the current version of Apache Maven.

Creating a Site

Maven can be used to generate an entire web site for your project. The web site can be used to house all of your user-facing documentation, generated as flat HTML with a common look and feel.

It also contains a number of generated documents based on the information in your project. This can include SCM information, mailing lists and a list of developers, as well as FAQs and release notes based on additional metadata you provide.

Finally, the web site will contain various reports about your source code generated by the plugins included in Maven such as javadocs, metrics, unit test results, changelogs, and more.

Adding Documents to the Site

Creating a Site Descriptor

To add documents to the site, first you will need to add them to the navigation so that they can be found.

To do this, create a navigation.xml file in the xdocs directory that contains the menu structure for the entire document tree. Add all items and sub-items.

For items that can collapse when you are not browsing them, add collapse="true" to the item declaration.

The following is an example navigation.xml file:

<?xml version="1.0" encoding="ISO-8859-1"?>

<project name="Maven xdoc Plugin">

  <!-- Page Title -->
  <title>Maven xdoc Plugin</title>

  <body>

    <!-- Links defined across the top right of the site -->
    <links>
      <item name="Maven"  href="http://maven.apache.org/"/>
    </links>

    <!-- Menu in the Left Navigation -->
    <menu name="Menu Name">
      <!-- Standalone item -->
      <item name="Item" href="/item.html" />

      <!-- Uncollapsed Submenu -->
      <item name="Alpha" href="/alpha/index.html">
        <item name="Alpha One" href="/alpha/one/index.html"/>
        <item name="Alpha Two" href="/alpha/two/index.html"/>
      </item>

      <!-- Collapsed Submenu -->
      <item name="Beta" href="/beta/index.html" collapse="true">
        <item name="Beta One" href="/beta/one/index.html" collapse="true"/>
        <item name="Beta Two" href="/beta/two/index.html" collapse="true"/>
      </item>
    </menu>
  </body>
</project>

Note: the href element should be absolute, referenced according to your document root (ie, under xdocs).

You can also add images to items in the menu, for example:

<item name="The Site" href="http://www.thesite.net/" img="http://www.thesite.net/thesite.png"/>

Creating a new Document

The XDoc format is quite simple, and is based on the original Anakia format that originated in Jakarta. The following is a sample XDoc document:

<document>
  <properties>
    <author email="user@company.com">John Doe</author>
    <title>Page Title</title>
  </properties>
  <!-- Optional HEAD element, which is copied as is into the XHTML <head> element -->
  <head>
    <meta ... />
  </head>
  <body>
    <!-- The body of the document contains a number of sections -->
    <section name="section 1">

      <!-- Within sections, any XHTML can be used -->
      <p>Hi!</p>

      <!-- in addition to XHTML, any number of subsections can be within a section -->
      <subsection name="subsection 1">
        <p>Subsection!</p>
      </subsection>
    </section>

    <section name="other section">

      <!-- You can also include preformatted source blocks in the document -->
      <source>
code line 1
code line 2
      </source>
    </section>
  </body>
</document>

To create one of these documents, create an XML file in the directory structure you want for your site under the xdocs document root. For example, /start/introduction.xml will be generated as /start/introduction.html on the final site.

Site Appearance

The following sections give some details on specific customisations you might want to make to the generated site.

For more information on customising the generated site, see the XDoc plugin reference.

Creating Your Own Index Page

Maven will generate a default index.html page for your project based on the description element in the POM. However, this is usually not very verbose, so you may like to create your own index page.

To do this, simply create an index.xml document in the base xdocs directory in the same style as the other documents (as explained in the previous sections), and this will be used instead of the generated document.

Visual Style

By default, all Maven-generated sites use the same look and feel for consistency. This enables users to easily recognize a Maven-generated site and immediately feel comfortable searching for information on the site.

Of course, we understand that users will want to customize their own sites. There are two alternatives.

Firstly, you can select different skins. Currently Maven comes with two skins - the current default and the "classic" skin that appeared in Maven 1.0 Beta 10 and earlier. Selection of the skin (and the colours used if using the classic skin) is done through properties given to the XDoc plugin.

The other alternative is to provide your own CSS. The Maven site is generated in XHTML and the layout defined by CSS. The best alternative is to take the existing stylesheet and modify it according to your tastes. To specify the alternate stylesheet, set the maven.xdoc.theme.url property for the XDoc plugin (again, see the properties for more information).

Reports

Finally, if you want to customize which reports are automatically generated for your site, you need to include the reports tag in your project descriptor. This tag enables you to selectively choose which reports to include and exclude as well as the order of the reports.

The following are the default set of reports, as specified by the XDoc plugin:

maven-changelog-plugin
maven-changes-plugin
maven-checkstyle-plugin
maven-developer-activity-plugin
maven-file-activity-plugin
maven-javadoc-plugin
maven-jdepend-plugin
maven-junit-report-plugin
maven-jxr-plugin
maven-license-plugin
maven-linkcheck-plugin
maven-pmd-plugin
maven-tasklist-plugin

Exclusion of All Maven-Generated Content

Users building documentation-only sites or sites that aggregate a lot of sub-projects might want to prevent the inclusion of the entire "Project Documentation" section of the navigation bar on their sites. This can be done by setting the maven.xdoc.includeProjectDocumentation property to the value of no. By default, Maven will include the "Project Documentation" section of the navigation bar which includes information about the project as well as links to the numerous Maven-generated reports.