10.2. Building a Project Site with Maven
To illustrate the process of building a project website, create a sample Maven project with the archetype plugin:
$ mvn archetype:create -DgroupId=org.sonatype.mavenbook -DartifactId=sample-project
This creates the simplest possible Maven project with one Java class in src/main/java and a simple POM. You can then build a Maven site by simply running mvn site. To build the site and preview the result in a browser, you can run mvn site:run, this will build the site and start an embedded instance of Jetty.
$ cd sample-project $ mvn site:run [INFO] Scanning for projects... [INFO] Searching repository for plugin with prefix: 'site'. [INFO] ------------------------------------------------------------------------ [INFO] Building sample-project [INFO]task-segment: [site:run] (aggregator-style) [INFO] ------------------------------------------------------------------------ [INFO] Setting property: classpath.resource.loader.class => 'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'. [INFO] Setting property: velocimacro.messages.on => 'false'. [INFO] Setting property: resource.loader => 'classpath'. [INFO] Setting property: resource.manager.logwhenfound => 'false'. [INFO] [site:run] 2008-04-26 11:52:26.981::INFO: Logging to STDERR via org.mortbay.log.StdErrLog [INFO] Starting Jetty on http://localhost:8080/ 2008-04-26 11:52:26.046::INFO: jetty-6.1.5 2008-04-26 11:52:26.156::INFO: NO JSP Support for /, did not find org.apache.jasper.servlet.JspServlet 2008-04-26 11:52:26.244::INFO: Started SelectChannelConnector@0.0.0.0:8080
Once Jetty starts and is listening to port 8080, you can see the project’s site when you go to http://localhost:8080/ in a web browser. You can see the results in Figure 10.1, “Simple Generated Maven Site”.
If you click around on this simple site, you’ll see that it isn’t very helpful as a real project site. There’s just nothing there (and it doesn’t look very good). Since the sample-project hasn’t configured any developers, mailing lists, issue tracking providers, or source code repositories, all of these pages on the project site will have no information. Even the index page of the site states, "There is currently no description associated with this project". To customize the site, you’ll have to start to add content to the project and to the project’s POM.
If you are going to use the Maven Site plugin to build your project’s site, you’ll want to customize it. You will want to populate some of the important fields in the POM that tell Maven about the people participating in the project, and you’ll want to customize the left-hand navigation menu and the links visible in the header of the page. To customize the contents of the site and affect the contents of the left-hand navigation menu, you will need to edit 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”.
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.
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.