Agility, Java programming, New technologies and more…
  • rss
  • Home
  • Management
  • Agile Programming
  • Technology
  • Linux
  • Event
  • Android app
  • Contact
  • About the author
  • English
  • Francais

Maven Site, one step further

Fabian Piau | Sunday April 4th, 2010 - 10:29 PM
  • Print
  • Twitter
  • LinkedIn
  • Facebook
  • Pocket

 Version française disponible

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.

17

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!

Maven-archetype-plugin

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 :

Project structure

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

or

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

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

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

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

The Maven default reports


Other content modifications

There are other possibilities of customization only by modifying the descriptor :

  • Add personal links to the banner;
  • Change the window title;
  • Change the position of the “Last Published” date;
  • Change the pictures ( “Built by Maven” logo, “Powered by” logo, pictures in the banner…);
  • Show the “Version” of your project (in our case, 1.0-SNAPSHOT);
  • etc.

You can get more information about the site descriptor.


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

Classic-site-skin

Default-site-skin

Default-site-skin

Stylus-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…

Cecilia-site-skin Embedchat-site-skin
Fluido-site-skin Wicket-site-skin
James-site-skin Mydoggy-site-skin
Lift-site-skin Netapsys-site-skin


Resources

  • The official “Maven-site” plugin website
  • The official skins repository
  • The ATP language reference
  • The FML language reference

Related posts

IT jobsComputing jobs simplified overview Java 11A Java 11 migration successful story springQCon London 2016 – Spring Framework 5 – Preview & Roadmap java-9QCon London 2016 – Project Jigsaw in JDK 9 – Modularity comes to Java
Comments
No Comments »
Categories
Agile programming
Tags
java, maven, maven-site
Comments rss Comments rss
Page 1 of 11
Download CarmaBlog App

RSS feeds

  • RSS feed RSS - Posts
  • RSS feed RSS - Comments

Most viewed posts

  • Changing the language in Firefox - 115,579 views
  • Using Google Forms / Drive / Docs to create an online survey - 63,166 views
  • FAQ – Online survey with Google Forms / Drive / Docs - 52,403 views
  • Customizing Gnome 3 (Shell) - 30,017 views
  • The meaning of URL, URI, URN - 17,251 views
  • Java EE & CDI vs. Spring - 15,442 views
  • Open Street Map, better map than Google Maps? - 14,648 views
  • Comparing NoSQL: Couchbase & MongoDB - 14,082 views
  • Firefox Nightly, Aurora, Beta, Desktop, Mobile, ESR & Co. - 13,087 views
  • API, REST, JSON, XML, HTTP, URI… What language do you speak? - 12,718 views

Recent Comments

  • Pauline on FAQ – Online survey with Google Forms / Drive / DocsMerci Fabian, mais le but étant que nos clients pu…
  • Fabian Piau on FAQ – Online survey with Google Forms / Drive / DocsProbablement mais ces options sont en général paya…
  • Pauline on FAQ – Online survey with Google Forms / Drive / DocsBonjour Fabian, Merci de votre retour, oui j'avais…
  • Fabian Piau on FAQ – Online survey with Google Forms / Drive / DocsBonjour Pauline, ce n'est pas possible de créer un…
  • Pauline on FAQ – Online survey with Google Forms / Drive / DocsBonjour, Je suis en train de créer un Google Forms…

Recent posts

  • How to write a blog post? At least my way! - 3 months and 2 weeks ago
  • Bot Attacks: You are not alone… - 1 year and 11 months ago
  • Flagger – Monitor your Canary deployments with Grafana - 2 years and 8 months ago
  • Flagger – Canary deployments on Kubernetes - 2 years and 10 months ago
  • Flagger – Get Started with Istio and Kubernetes - 2 years and 10 months ago
  • Expedia CoderDojo in London - 3 years and 7 months ago
  • Volunteering at Devoxx4Kids - 3 years and 10 months ago
  • A Java 11 migration successful story - 4 years and 2 months ago
  • Tips to make your WordPress website secure - 4 years and 5 months ago
  • Devoxx UK 2018 – Day 2 - 4 years and 9 months ago
  • Devoxx UK 2018 – Day 1 - 4 years and 9 months ago
  • Wise, Revolut and Monzo, a small revolution for travelers and expats - 5 years and 1 month ago
  • Autocomplete for Git - 5 years and 10 months ago
  • Swagger, the automated API documentation - 6 years and 2 weeks ago
  • Microservices architecture – Best practices - 6 years and 5 months ago
Buy me a coffee

Language

  • Français
  • English

Follow me!

Follow me on Linkedin
Follow me on Twitter
Follow me on Stackoverflow
Follow me on Github
Follow me on Rss
Link to my Contact

Email subscription

Enter your email address to receive notifications of new posts.

Tags

.net agile agility android bash best practices blog cache cloud computing conference continuous integration css developer devoxx docker eclipse extreme programming firefox flagger google helm hibernate istio java job jug kubernetes london mobile computing overview performance plugin programmer script security sharing society spring tdd test tool ubuntu windows wordpress

Links

  • Blog Ippon Technologies
  • Blog Publicis Sapient
  • Blog Zenika
  • Classpert
  • CommitStrip
  • Coursera
  • Le Touilleur Express
  • Les Cast Codeurs Podcast
  • OCTO talks !
  • The Twelve-Factor App

Categories

  • Event (15)
  • Linux (3)
  • Management (8)
  • Agile programming (29)
  • Technology (45)

Archives

  • December 2022 (1)
  • April 2021 (1)
  • June 2020 (1)
  • May 2020 (2)
  • July 2019 (1)
  • May 2019 (1)
  • December 2018 (1)
  • October 2018 (1)
  • June 2018 (1)
  • May 2018 (1)
  • January 2018 (1)
  • May 2017 (1)
  • March 2017 (1)
  • October 2016 (1)
  • April 2016 (2)
  • March 2016 (1)
  • November 2015 (1)
  • May 2015 (1)
  • February 2015 (1)
  • December 2014 (1)
  • November 2014 (1)
  • September 2014 (2)
  • August 2014 (1)
  • July 2014 (2)
  • June 2014 (1)
  • April 2014 (1)
  • March 2014 (1)
  • February 2014 (2)
  • January 2014 (1)
  • December 2013 (1)
  • November 2013 (1)
  • October 2013 (3)
  • September 2013 (5)
  • July 2013 (1)
  • June 2013 (1)
  • May 2013 (1)
  • April 2013 (1)
  • March 2013 (2)
  • February 2013 (1)
  • January 2013 (2)
  • December 2012 (2)
  • October 2012 (1)
  • September 2012 (1)
  • July 2012 (1)
  • May 2012 (1)
  • April 2012 (1)
  • March 2012 (1)
  • February 2012 (1)
  • January 2012 (2)
  • December 2011 (1)
  • November 2011 (2)
  • October 2011 (2)
  • September 2011 (1)
  • July 2011 (1)
  • June 2011 (2)
  • April 2011 (1)
  • March 2011 (1)
  • February 2011 (1)
  • January 2011 (2)
  • November 2010 (2)
  • September 2010 (1)
  • August 2010 (1)
  • July 2010 (1)
  • June 2010 (1)
  • May 2010 (1)
  • April 2010 (1)
  • March 2010 (1)
  • February 2010 (1)
  • December 2009 (1)
  • November 2009 (1)
  • October 2009 (2)
  • September 2009 (2)
  • August 2009 (3)
  • July 2009 (1)
  • June 2009 (2)
Follow me on Twitter
Follow me on Linkedin
Follow me on Stackoverflow
Follow me on Rss
Link to my Contact
Follow me on Github
 
Fabian Piau | © 2009 - 2023
All Rights Reserved | Top ↑