This section lists some useful tips and tricks you can use when creating a Maven site.
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>
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>
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>
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
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>
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.
