Sonatype.com

Maven: The Complete Reference
10.3. Customizing the Site Descriptor

10.3. Customizing the Site Descriptor

When you add content to the site, you are going to want to modify the left-hand navigation menu that is generated with your site. The following site descriptor customizes the logo in the upper left-hand corner of the site. In addition to customizing the header of the site, this descriptor adds a menu section to the left-hand navigation menu under the heading "Sample Project". This menu contains a single link to an overview page.

An Initial Site Descriptor.  

<project name="Sample Project">
    <bannerLeft>
        <name>Sonatype</name>
        <src>images/logo.png</src>
        <href>http://www.sonatype.com</href>
    </bannerLeft>
    <body>
        <menu name="Sample Project">
            <item name="Overview" href="index.html"/>
        </menu>
        <menu ref="reports"/>
    </body>
</project>

This site descriptor references one image. This logo.png image should be placed in ${basedir}/src/site/resources/images. In addition to the change to the site descriptor, you’ll want to create a simple index.apt page in ${basedir}/src/site/apt. Put the following content in index.apt, it will be transformed to the index.html and serve as the first page a user sees when they come to your project’s Maven-generated web site.

  Welcome to the Sample Project, we hope you enjoy your time
on this project site.  We've tried to assemble some
great user documentation and developer information, and
we're really excited that you've taken the time to visit
this site.

What is Sample Project

Well, it's easy enough to explain.   This sample project is
a sample of a project with a Maven-generated site from
Maven: The Definitive   Guide.   A dedicated team of volunteers
help maintain this sample site, and so on and so forth.

To preview the site, run mvn clean site followed by mvn site:run:

$ mvn clean site
$ mvn site:run

Once you do this, load the page in a browser by going to http://localhost:8080. You should see something similar to the screenshot in Figure 10.2, “Customized Sample Project Web Site”.

figs/web/site_custom-descriptor.png

Figure 10.2. Customized Sample Project Web Site


10.3.1. Customizing the Header Graphics

To customize the graphics which appear in the upper left-hand and right-hand corners of the page, you can use the bannerLeft and bannerRight elements in a site descriptor.

Adding a Banner Left and Banner Right to Site Descriptor.  

<project name="Sample Project">

    <bannerLeft>
        <name>Left Banner</name>
        <src>images/banner-left.png</src>
        <href>http://www.google.com</href>
    </bannerLeft>

    <bannerRight>
        <name>Right Banner</name>
        <src>images/banner-right.png</src>
        <href>http://www.yahoo.com</href>
    </bannerRight>
    ...
</project>

Both the bannerLeft and bannerRight elements take name, src, and href child elements. In the site descriptor shown above, the Maven Site plugin will generate a site with banner-left.png in the left-hand corner of the page and banner-right in the right-hand corner of the page. Maven is going to look in ${basedir}/src/site/resources/images for these images.

10.3.2. Customizing the Navigation Menu

To customize the contents of the navigation menu, use the menu element with item child elements. The menu element adds a section to the left-hand navigation menu. Each item is rendered as a link in that menu.

Creating Menu Items in a Site Descriptor.  

<project name="Sample Project">
    ...
    <body>

        <menu name="Sample Project">
            <item name="Introduction" href="index.html"/>
            <item name="News" href="news.html"/>
            <item name="Features" href="features.html"/>
            <item name="Installation" href="installation.html"/>
            <item name="Configuration" href="configuration.html"/>
            <item name="FAQ" href="faq.html"/>
        </menu>
        ...
    </body>
</project>

Menu items can also be nested. If you nest items, you will be creating a collapsible menu in the left-hand navigation menu. The following example adds a link "Developer Resources" which links to /developer/index.html. When a user is looking at the Developer Resources page, the menu items below the Developer Resources menu item will be expanded.

Adding a Link to the Site Menu.  

<project name="Sample Project">
    ...
    <body>
        ...
        <menu name="Sample Project">
            ...
            <item name="Developer Resources" href="/developer/index.html"
                  collapse="true">
                <item name="System Architecture" href="/developer/architecture.html"/>
                <item name="Embedder's Guide" href="/developer/embedding.html"/>
            </item>
        </menu>
        ...
    </body>
</project>

When an item has the collapse attribute set to true, Maven will collapse the item until a user is viewing that specific page. In the previous example, when the user is not looking at the Developer Resources page, Maven will not display the System Architecture and Embedder’s Guide links; instead, it will display an arrow pointing to the Developer Resources link. When the user is viewing the Developer Resources page it will show these links with an arrow pointing down.