| 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. 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 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 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
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:
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:
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 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>
WarningDoxia 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. |
 |
 |
Become a Member
|
