In recent times, Maven Sites came close to becoming extinct. Maven Plugins were still using them for the wonderful automatic documentation page (named goals), but regular projects were not using them anymore.

However, Maven Sites have some huge benefits such as keeping the documentation close to the code, and automatically providing reports, information and API docs (Javadoc). Being able to release the documentation at the same time as the code was also a great advantage.

So why was this feature not used? Several reasons:

• The look and feel was terrible.
• The apt syntax was terrible.
• The customization was terrible.

Now, though, it’s possible to create much better Maven Sites using Twitter Bootstrap for the skinning and Markdown for the editing. Even better, if you use GitHub, your site can be automatically updated on your project’s GitHub page.

This blog post explains how to use all these new features.

The before / after comparison

First, a reminder of what old-school Maven sites look like:

Contrasted with what we can expect now:

Much better, isn’t it? So, let’s have a look at how to build this kind of site.

What are the benefits of Maven sites?

The main benefit of Maven sites is the ability to keep your documentation and your code together. So it’s much easier to keep everything in sync, and it avoids using a separate wiki or CMS, where the documentation is never really up to date.

The second huge benefit is the ability to release your documentation at the same time as your project. When you release your project, the web site is immediately updated with the new documentation.

Finally, you benefit from all the automatically generated pages such as Project Team, Continuous Integration, Source Repository, and Mailing Lists. All the information your users may need is there and is extracted from your pom file. Moreover, some reports can also be generated, such as Javadoc and the navigable version of your code.

Creating a site

First of all, let’s create a (regular) Maven site. This project shows the basic structure to create a regular Maven site.

The regular Maven site supports 3 types of documents:

• APT: a markup language pretty close to plain text
• XDOC: another markup language closer to HTML / XML
• FML: another markup language for FAQ entries

Generally, you will choose between APT and XDOC.

The sources of the site reside under src/site. Resources (images, documents) are in src/site/resources and your pages in src/site/apt or src/site/xdoc.

The src/site/site.xml file describes the site configuration, especially the menu. For now, just concentrate on the menu elements in this site.xml file. The first one contains links to html pages (that we generate). The second one specifies a reference: it’s where the reports will be placed.

In your pom file, you just declare the maven-site-plugin to instruct Maven to generate the site with mvn site.

Open target/site/index.html with your browser and you should get:

Well, ok, we have a site, but the syntax is not really what we want to use today, and the look is a bit ugly. Want to see the syntax? Check out src/site/apt/format.apt and src/site/xdoc/xdoc.xml.

Pimp my Maven Site with Twitter Bootstrap

First things first: let’s improve the style. By configuring the fluido skin, the maven site is then using Twitter Bootstrap, making the web site that much better. The icing on the cake is that this skin has plenty of options to support sidebar and header bar, social widgets (Google+, Facebook, Twitter), GitHub ribbon, Google search… More info on http://maven.apache.org/skins/maven-fluido-skin/.

Using this skin is very simple. In the site.xml file, add:

    <skin>
        <groupId>org.apache.maven.skins</groupId>
        <artifactId>maven-fluido-skin</artifactId>
        <version>1.2.1</version>
    </skin>
    <custom>
        <fluidoSkin>
            <sideBarEnabled>true</sideBarEnabled>
        </fluidoSkin>
    </custom>

Regenerate the site and now you should get:

Using Markdown

Markdown is a wiki syntax popularized by GitHub. It’s a pretty simple syntax, easy to use and to learn. A lot of tools such as GitHub and Gitblit are also able to render Markdown directly. All these benefits make Markdown a pretty good candidate for writing documentation.

Let’s now migrate the index.apt page to Markdown (index.md):

	Markdown Maven Site
	===================

	Congratulations! If you are looking at this page then you have successfully generated a maven site using
	the markdown syntax !

	You added the following snippet to your _pom_ file:

	    <dependencies>
	        <dependency>
	            <groupId>org.kohsuke</groupId>
	            <artifactId>doxia-module-markdown</artifactId>
	            <version>1.0</version>
	        </dependency>
	    </dependencies>

	And you generated the web site using:

	    mvn site

Then, after having deleted the index.apt file, regenerate the web site using mvn site, and you should get:

As you can see, this site is mixing several syntaxes. So, if you already have a Maven site, you can decide to just write new pages using Markdown, while keeping old pages unchanged.

Using macros

One of the great benefits to using a Maven site is the filtering capabilities. This means the ability to use variables in your pages such as ${project.version}. So no need to search for all occurrences of the version in all your pages, just use this variable. All Maven variables and properties are supported.

To enable filtering on a file, append .vm. to the file name (vm meaning Velocity Macro).

For example, to our previous Markdown page, let’s append:

This web site was generated for ${project.groupId}:${project.artifactId}:${project.version}.

Rename the index.md file to index.md.vm to enable macro processing. Then regenerate the web site, and you should get:

Using GitHub pages to host the site

Github is known for being a great place to host source code. But you can also host web pages for each project. To do so, you just need to create a gh-pages branch.

The great news is that you can use this space to store your Maven site. Indeed, GitHub has even provided a Maven plugin to automatically update your site there.

To achieve this, you first need to configure the scm details of your project in the pom.xml file, e.g.:

	<scm>
	        <connection>scm:git:git@github.com:akquinet/maven-site-tutorial.git</connection>
	        <url>https://github.com/akquinet/maven-site-tutorial</url>
	        <developerConnection>scm:git:git@github.com:akquinet/maven-site-tutorial.git</developerConnection>
	</scm>

Then, we need to configure the github-site-plugin. In the plugins section of your pom.xml file, add:

<plugin>
    <groupId>com.github.github</groupId>
    <artifactId>site-maven-plugin</artifactId>
    <version>0.5</version>
    <executions>
        <execution>
            <goals>
                <goal>site</goal>
            </goals>
            <phase>site-deploy</phase>
            <configuration>
            		<path>${project.version}</path>
                <merge>true</merge>
            </configuration>
        </execution>
    </executions>
</plugin>

We trigger the deployment of the site during the site-deploy phase. To prevent the regular site deployment from happening, we need to add an additional configuration parameter to the maven-site-plugin.

<plugin>
     <artifactId>maven-site-plugin</artifactId>
     <configuration>
         <skipDeploy>true</skipDeploy>
     </configuration>
    [...]
</plugin>

The path parameter indicates the directory where the site will be deployed. For reasons of traceability, we use ${project.version} to distinguish versions. However, if you prefer, you can use a static url.

The last configuration we need to add is the GitHub authentication parameters. The plugin uses two properties:

• github.global.userName for the user name
• github.global.password for the password

We recommend to create a new (automatically activated) profile in ~/.m2/settings.xml defining those properties, e.g.:

	<profile>
		<id>github</id>
		<properties>
			<github.global.userName>cescoffier</github.global.userName>
			<github.global.password>secret</github.global.password>
		</properties>
	</profile>
	[...]
	<activeProfiles>
		[...]
		<activeProfile>github</activeProfile>
	</activeProfiles>

Once done, we can deploy our web site on GitHub with mvn site-deploy:

[INFO] --- site-maven-plugin:0.5:site (default) @ maven-github-site ---
[INFO] Creating 50 blobs
[INFO] Creating tree with 50 blob entries
[INFO] Merging with tree dc3f3775c434365df2832b13f93a2e0dff256627
[INFO] Creating commit with SHA-1: 8d949b949d6be69631a62de586480d3a6462d270
[INFO] Updating reference refs/heads/gh-pages from 1d4395cdc847bedafef22251ef7b755427c5f211 to 8d949b949d6be69631a62de586480d3a6462d270


Note that the page creation takes several minutes the first time (you will receive a mail once it’s done). After this first deployment, the new web site is deployed instantaneously. So, we can check the web site on: http://[username].github.com/%5Bprojectname%5D/%5Bprojectversion%5D. In our case: http://akquinet.github.com/maven-site-tutorial/1.0-SNAPSHOT/

Conclusion

This post has shown how you can used maven site to manage project’s documentation without having to suffer from the old look and feel and weird syntax. This is just an overview of what can be achieved with Maven Sites.