April 2010 | CarmaBlog

Maven Site, one step further

Fabian Piau | Sunday April 4th, 2010 - 10:29 PM

Introduction

If your project is mavenized (i.e. using Maven), it would be a pity not to use every possibilities from Maven, especially the Maven Site.

With little effort, you can have a quality and low maintenance project website. When it is well configured, the Maven Site could become the “showcase” of your project by centralizing its more useful information. Maven sites are frequently used on open source projects.

Information can be general (project description, team, dependences…), specific (Checkstyle, PMD, Javadoc, SureFire, Cobertura reports) or what you want like a FAQ (Frequently Asked Questions)…

This online tutorial will teach you how to personalize the basic site generated by Maven.

Requirements: Maven must be installed on your machine.

Maven version used : 2.0.9. Depending on the version you are using, command-lines could be slightly different.

Project creation

Throughout this tutorial, we will use a Maven 2 project generated with the Archetype plugin.

In a terminal, type:

mvn archetype:generate

Choose the “maven-archetype-site” model. It will generate a complete Maven Site structure.

Archetype requires additional information :

GroupId : demo.mavensite.personalization;
ArtifactId : maven-site-personalization;
Version : Press directly the return key, the 1.0-SNAPSHOT version is fine;
The base package for the source : The ArtifactId is reused by default. Perfect, so press the return key again!

Archetype displays a final summary, validate your choice by pressing return one last time.

The project is now created.

The created project at a glance

A folder “maven-site-personalization” has been created.

The structure is as follows :

A “fr” folder? Yes! Maven Site is supporting internationalization. By default, the site generated with Archetype is available in English (default version) & in French.

Here is a description of the various files created.

site.xml : The site descriptor. It is responsible for site layout (banner, links, the left menu). In one way, it is the starting point of the generation;
site_fr.xml : The French site descriptor;
Every other files represent one page in the site. No HTML here, all files are written in specific format understandable by Maven. Then, they will be processed to generate HTML.

The example site reuses the 3 different formats (APT, Xdoc & FML).

Xdoc format : An XML format, used since Maven 1.x;
APT “Almost Plain Text” format : Wiki-like format that allows you to write structured documents. It is the “replacement” for Xdoc because more convenient;
FML format : Designed specifically for FAQ pages.

Site generation

After this structure review, we are going to generate the site with only one command :

mvn site

mvn site:run

that will build the site and start an embedded instance of Jetty.

The generated site is available at /target/site/index.html (or http://localhost:8080 if you have chosen Jetty)

The generated Maven Site

This is a very simple site by default. To access the French version, change the path by /site/fr/index.html (or go on http://localhost:8080/fr).

Switching between languages is a bit painful, isn’t it?

We will describe how to switch between 2 languages in a more convenient way next.

Adding a new page

To add a new page to the site, you just need to add one file to one of the 3 folders ( “apt”, “fml” or “xdoc” ).

For example, I added the file “my_new_category.apt” containing some well-formatted text to the “apt” folder.

Then you need to reference it in the site descriptor.

<?xml version='1.0' encoding='ISO-8859-1'?>
<project name='Maven'>
  <bannerLeft>
    <name>Maven</name>
    <src>http://maven.apache.org/images/apache-maven-project.png</src>
    <href>http://maven.apache.org/</href>
  </bannerLeft>
  <bannerRight>
    <src>http://maven.apache.org/images/maven-small.gif</src>
  </bannerRight>
  <body>
    <links>
      <item name='Apache' href='http://www.apache.org/' />
      <item name='Maven 1.0' href='http://maven.apache.org/'/>
      <item name='Maven 2' href='http://maven.apache.org/maven2/'/>
    </links>
    <menu name='Maven 2.0'>
      <item name='APT Format' href='format.html'/>
      <item name='FAQ' href='faq.html'/>
      <item name='Xdoc Example' href='xdoc.html'/>
      <item name='My new category' href='my_new_category.html'/>	  
    </menu>
  </body>
</project>

Regenerate the site

mvn clean site

and a new item will appear in the menu, which is a link to your new page.

Adding one page

I took the opportunity to show you some features of ATP (tables, lists, titles, formatting…)

Internationalize your site easily

We are going to add switch-language links in the menu.

In site.xml :

<project name='Maven'>
  [...]
  <body>
    [...]
    <menu name='Other languages'>
      <item name='Français' href='/fr/index.html'/> 
    </menu>
  </body>
</project>

In site_fr.xml :

<project name='Maven'>
  [...]
  <body>
    [...]
    <menu name='Autres langues'>
      <item name='English' href='../index.html'/> 
    </menu>
  </body>
</project>

Site internationalization

The default language is English. To change this, it is necessary to modify the project’s POM.

fr

Only French language is available.

en,fr

English is the default language, French is available.

fr,en

French is the default language, English is available.

fr,en,es,de

The site is multilingual, available in Spanish and German.

Adding the Maven default reports

As you can see, that is very easy to add some pages, modify the site layout…

You will notice that the Maven default reports (general information on the project) are not included in the site.

You just have to add one tag, like so :

<project>
  [...]
  <body>
    [...]
    <menu ref='reports'/>
  </body>
/project>

The Maven default reports

Skinning your site

It is possible to change the look and feel of your site in a consistent way.

To do that and one more time, you only need to modify the site descriptor (not the POM) by adding :

<project>
  [...]
  <skin>
    <groupId>org.apache.maven.skins</groupId>
    <artifactId>maven-stylus-skin</artifactId>
    <version>1.2</version>
  </skin>
  [...]
</project>

At the time of this article’s writing, there are only 3 official themes available.

maven-classic-skin (old theme, version 1.0);
maven-default-skin (default theme, version 1.0);
maven-stylus-skin (theme used by the official Maven website, version 1.2).

Classic-site-skin

Default-site-skin

Stylus-site-skin

After some internet searches, you will manage to find some more.

With one site descriptor per language, the translated site can evolve independently. For example, that’s completely possible to have different skins for the French and English versions.

Go further with customization

To obtain a site just like you want, it is possible to go even further by modifying yourself the design.

It is possible to add your own images, your CSS stylesheets, your specific links on the project and so on. Don’t limit yourself to the basic functions!

Then if you are satisfied with your new design, you can package all your modifications in one file (a skin) and make it available to everyone.

Here is a selection of skins I particularly appreciated. We would almost forgot that we are talking about Maven Sites…