Maven: The Complete Reference

10.8. Tips and Tricks

This section lists some useful tips and tricks you can use when creating a Maven site.

10.8.1. Inject XHTML into HEAD

To inject XHTML into the HEAD element, add a head element to the body element in your project’s Site descriptor. The following example adds a feed link to every page in the sample-project web site.

Injecting HTML into the HEAD element. 

<project name="Hello World">
    ...
    <body>
        <head>
            <link href="http://sample.com/sites/sample-project/feeds/blog"
                  type="application/atom+xml"
                  id="auto-discovery"
                  rel="alternate"
                  title="Sample Project Blog" />
        </head>
        ...
    </body>
</project>

10.8.2. Add Links under Your Site Logo

If you are working on a project which is being developed by an organization, you may want to add links under your project’s logo. Assume that your project is a part of the Apache Software Foundation, you might want to add a link to the Apache Software Foundation web site right below your logo, and you might want to add a link to a parent project as well. To add links below your site logo, just add a links element to the body element in the Site descriptor. Each item element in the links element will be rendered as a link in a bar directly below your project’s logo. The following example would add a link to the Apache Software Foundation followed by a link to the Apache Maven project.

Adding Links Under Your Site Logo. 

<project name="Hello World">
    ...
    <body>
        ...
        <links>
            <item name="Apache" href="http://www.apache.org"/>
            <item name="Maven" href="http://maven.apache.org"/>
        </links>
        ...
    </body>
</project>

10.8.3. Add Breadcrumbs to Your Site

If your hierarchy exists within a logical hierarchy, you may want to place a series of breadcrumbs to give the user a sense of context and give them a way to navigate up the tree to projects which might contain the current project as a subproject. To configure breadcrumbs, add a breadcrumbs element to the body element in the site descriptor. Each item element will render a link, and the items in the breadcrumbs element will be rendered in order. The breadcrumb items should be listed from highest level to lowest level. In the following site descriptor, the Codehaus item would be seen to contain the Mojo item.

Configuring the Site’s Breadcrumbs. 

<project name="Sample Project">
    ...
    <body>
        ...
        <breadcrumbs>
            <item name="Codehaus" href="http://www.codehaus.org"/>
            <item name="Mojo" href="http://mojo.codehaus.org"/>
        </breadcrumbs>
        ...
    </body>
</project>

10.8.4. Add the Project Version

When you are documenting a project that has multiple versions, it is often very helpful to list the project’s version number on every page. To display your project’s version on the website, simply add the version element to your site descriptor:

Positioning the Version Information. 

<project name="Sample Project">
    ...
    <version position="left"/>
    ...
</project>

This will position the version (in the case of the sample-project project, it will say "Version: 1.0-SNAPSHOT") in the upper left-hand corner of the site, right next to the default "Last Published" date. Valid positions for the project version are:

left
Left side of the bar just below the site logo
right
Right side of the bar just below the site logo
navigation-top
Top of the menu
navigation-bottom
Bottom of the menu
none
Suppress the version entirely

10.8.5. Modify the Publication Date Format and Location

In some cases, you may wish to reformat or reposition the "Last Published" date for your project website. Just like the project version tip above, you can specify the position of the publication date by using one of the following:

left
Left side of the bar just below the site logo
right
Right side of the bar just below the site logo
navigation-top
Top of the menu
navigation-bottom
Bottom of the menu
none
Suppress the publication entirely

Positioning the Publish Date. 

<project name="Sample Project">
    ...
    <publishDate position="navigation-bottom"/>
    ...
</project>

By default, the publication date will be formatted using the date format string MM/dd/yyyy. You can change this format by using the standard notation found in the JavaDocs for SimpleDateFormat (see JavaDoc for SimpleDateFormat for more information). To reformat the date using yyyy-MM-dd, use the following publishDate element.

Configuring the Publish Date Format. 

<project name="Sample Project">
    ...
    <publishDate position="navigation-bottom" format="yyyy-MM-dd"/>
    ...
</project>

10.8.6. Using Doxia Macros

In addition to its advanced document rendering features, Doxia also provides a macro engine that allows each input format to trigger injection of dynamic content. An excellent example of this is the snippet macro, which allows a document to pull a code snippet out of a source file that’s available via HTTP. Using this macro, a small fragment of APT can be rendered into XHTML. The following APT code calls out to the snippet macro. Please note that this code should be on a single continuous line, the black slash character is inserted to denote a line break so that this code will fit on the printed page.

%{snippet|id=modello-model|url=http://svn.apache.org/repos/asf/maven/\
archetype/trunk/maven-archetype/maven-archetype-model/src/main/\
mdo/archetype.mdo}

Output of the Snippet Macro in XHTML. 

<div class="source"><pre>

        <model>
            <id>archetype</id>
            <name>Archetype</name>
            <description><![CDATA[Maven's model for the archetype descriptor.
]]></description>
            <defaults>
                <default>
                    <key>package</key>
                    <value>org.apache.maven.archetype.model</value>
                </default>
            </defaults>
            <classes>
                <class rootElement="true" xml.tagName="archetype">
                    <name>ArchetypeModel</name>
                    <description>Describes the assembly layout and packaging.</description>
                    <version>1.0.0</version>
                    <fields>
                        <field>
                            <name>id</name>
                            <version>1.0.0</version>
                            <required>true</required>
                            <type>String</type>
                        </field>
                        ...
                    </fields>
                </class>
            </classes>
        </model>

</pre></div>

Warning

Doxia macros MUST NOT be indented in APT source documents. Doing so will result in the APT parser skipping the macro altogether.

For more information about defining snippets in your code for reference by the snippet macro, see the Guide to the Snippet Macro on the Maven website, at http://maven.apache.org/guides/mini/guide-snippet-macro.html.