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.

The navigation file

Here is a template for a typical navigation file:

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

<project name="My project">

  <title>My project title</title>

  <body>

    <breadcrumbs>
      <item name="Home"             href="/index.html"/>
        .
    </breadcrumbs>

    <links>
      <item name="Home"             href="/index.html"/>
        .
    </links>

    <sitemap/>

    <menu name="Documentation">
        .
    </menu>
        .

    <search/>

    <powered-by>
        .
    </powered-by>

    <footer>
        .
    </footer>

  </body>
</project>

There has to be at least one <menu> element present in the documents body, all other elements are optional. The core elements of this navigation file are described in a section of the main Maven site, we'll just discuss the few additions here.

Breadcrumbs

A list of items that are displayed on the top left of the site. Check the top of this page for an example.

Sitemap

If a <sitemap/> element is found in the navigation.xml body, a sitemap.html file is generated. An optional description is added for a page if a <meta> element is found in the corresponding xdoc source document header:

<head>
  <meta name="description" content="Information on the navigation.xml file format"/>
</head>

See the sitemap of the current site for an example.

Menu

The <menu> element takes an optional type attribute which can be set to "header" or "footer". This will put the corresponding menu on top or on bottom of the navigation menu, respectively.

To open a link in a new window, use the "target" attribute. For example, for a menu item:

<item name="Name" href="URL" target="_blank"/>

XDoc automatically adds the "Opens in a new window" icon and "New Window" tooltip to links with the "target" attribute.

XDoc also automatically adds the "External Link" icon and tooltip to links referring to external sites (actually, any absolute url).

Google Search

If a <search/> element is found in the navigation.xml body, a search navigation menu is generated that uses google.

Additional 'powered-by' logos

You can add additional 'powered-by' logos above the maven logo by specifying a <powered-by> element in the body of navigation.xml, e.g.:

<powered-by>
  <item
    name="Hosted by SourceForge"
    href="http://www.sourceforge.net"
    img="http://sourceforge.net/sflogo.php?group_id=16035&amp;type=1"/>
</powered-by>

You may specify several items to include more logos.

Footer

You can use the footer tag for including text or images just below the navigation menu and above the copyright notice. This tag is only useful in the navigation.xml file and should be placed within the body element. For example:

<!-- footer will be placed above the (c) -->
   <footer>
    <a href="http://sourceforge.net/projects/ctecl">
      <img src="http://sourceforge.net/sflogo.php?group_id=72748" border="0" alt="sf logo"/>
    </a>
   </footer>

Validation

The xdoc:navigation-validate goal can be used to check whether your ${maven.xdoc.navigation.file} is a valid navigation.file. Validation is performed against this xsd. Note that the order of elements is important and should be the same as in the example above.