Section 2.10. Customizing Site Look and Feel

2.10. Customizing Site Look and Feel

Your weather application is complete, but the Maven-generated site has the same look and feel as every other Maven project. Change the look and feel.

2.10.1. How do I do that?

Customize the behavior of the XDoc plug-in. Take a look at the following properties from project.properties:

maven.xdoc.date = right maven.xdoc.date.format = MM/dd/yyyy maven.xdoc.crumb.separator = > maven.xdoc.developmentProcessUrl = http://www.slashdot.org maven.xdoc.poweredBy.title = Powered by the Mighty Maven maven.xdoc.theme.url=./style/custom.css

These properties set the location and format of the site date, the breadcrumb separator, the development process URL, and the "Powered by" title. Run maven site, and you will see how these properties made subtle changes to the generated site. Changing the development process URL is important if your organization maintains a page dedicated to your development process. If you leave this property unchanged it will point to a page on the maven.apache.org web site.

2.10.2. What just happened?

To customize the look and feel, you will need to alter the CSS used by Maven. To get a sense of the styles used in the Maven theme, take a look at the target/docs/style directory of your generated Maven site. Here you will find files named maven-base.css, maven-classic.css, and maven-theme.css. You will need to override these styles to customize the look and feel of Maven. The file is stored in xdocs/style/custom.css, and is specified by the maven.xdoc.theme.url property and referenced in a generated Maven web site.

For a full list of customizable properties in the XDoc plug-in, take a look at the XDoc plug-in's online documentation at http://maven.apache.org/reference/plugins/xdoc/. If you want to get a sense of how to customize a Maven-generated web site, the best place to look is at another project which uses Maven. One project which uses Maven to generate its web site is the Maven project itself (surprise!). Figure 2-2 shows a screenshot of the Maven web site.

Figure 2-2. Screenshot of a customized Maven web site

The Maven site has customized navigation, external links, date formatting, and PDF generation for the entire site. If you want to customize your site, you should take a look at the xdocs directory in the Apache Subversion repository (http://cvs.apache.org/viewcvs.cgi/maven/maven-1/core/trunk/xdocs/?root=Apache-SVN). Apache has configured ViewCVS to point to the repository which holds the Maven 1 web site project, and you can use this tool to gain insight into how to customize your build. For example, if you take a look at the navigation.xml document in the /maven/maven-1/core/trunk/xdocs directory, you will see that the following XML fragment defines a collapsible menu item, as shown in the User's Guide section of the navigation in Figure 2-2:

<menu name="User's Guide">   <item name="Using Maven" collapse="true" href="/using/index.html">     <item name="Building JARs" href="/using/jar.html" />     <item name="Resources" href="/using/resources.html" />     <item name="Unit Testing" href="/using/tests.html" />   </item>   <item name="Customizing a Build" collapse="true"        href="/using/customising.html">     <item name="Scripting" href="/reference/scripting.html" />     <item name="Writing a Plugin" href="/using/developing-plugins.html" />     <item name="Sharing Plugins" href="/reference/sharing-plugins.html" />   </item>   <item name="Repositories" collapse="true"        href="/using/repositories.html">     <item name="Internal Repositories"          href="/reference/internal-repositories.html" />     <item name="Sun JAR Names"          href="/reference/standard-sun-jar-names.html" />     <item name="Uploading to Ibiblio"          href="/reference/repository-upload.html" />   </item>   <item name="Reference" collapse="true" href="/reference/index.html">     <item name="Glossary" href="/reference/glossary.html" />     <item name="Conventions" href="/reference/conventions.html" />     <item name="Project Descriptor" href="/reference/project-descriptor.html" />     </item>   </item> </menu>

In the same directory, you can take a look at the Maven FAQ in faq.fml, and other XDoc documents which are used to create a Maven project web site with comprehensive documentation. Use the Maven project's document as a guide for your own commercial or open source project.