Maven Sites – Reloaded

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://%5Busername%5D.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.

25 Responses to Maven Sites – Reloaded

  1. SIlvio says:

    very nice article. in my company we use maven site, but we are facing the limitation of not having a strong search capability in the generated site. I am now evaluating alternatives such as using a maven confluence plugin to deploy the site in confluence which has search integrated. would you suggest alternatives, knowing that at the moment the corporate tool to share docs is sharepoint? is there a way to export the maven site into sharepoint?

    • Clement Escoffier says:

      Hi,

      Not sure about share point but the Maven fluido skin support google search: Regards,

      Clement

      • Silvio says:

        thanks Clement, but I dont want to make my site public. I just want to have a search engine for the developers to browse quickly the maven site. That’s why I was thinking to export the site to confluence. any other idea is welcome

  2. cerker says:

    Our maven-latex-plugin generates PDF and HTML from LaTeX sources. Thus LaTeX documentation can be incorporated into the site built by Maven.

    Check out https://github.com/akquinet/maven-latex-plugin

  3. Simon says:

    I had to add

    3.1

    to the maven-site-plugin plugin to get the maven-markdown-site project to run. Otherwise maven3.0.3 was defaulting to an earlier version of the site plugin which was giving an error.

  4. declanhynes says:

    Reblogged this on Adventures in tech and commented:
    akquinet has a nice post on how to improve the skin that is used on a typical Maven Site.

  5. Tuukka Mustonen says:

    A drawback is that producing PDF out of markdown markup is not supported by maven-pdf-plugin. One could try using doxia-book-maven-plugin, but at least I didn’t have luck with that. I got this error (apparently faced by few other users as well): http://maven.40175.n5.nabble.com/doxia-book-maven-plugin-How-do-I-bind-book-sections-to-markdown-files-td5716764.html

    Maybe doxia just doesn’t support Markdown in PDF creation.

    • Antoine says:

      I’m facing the same issue. The maven-pdf-plugin fails generating the pdf and the doxia-book-maven-plugin with the doxia-module-markdown integrates the raw html generated from the md file into the pdf.

      Did you find another solution to generate a PDF document from the markdown sources?

  6. Mark Michaelis says:

    Thanks for the provided tips. Actually I am still struggling having a multi-module layout as the site-maven-plugin seems to try to deploy all modules to the same folder thus overriding information from another module. Failed to find a nice solution yet which also guarantees that the relative links provided by Maven Site work.

    Another point: Mind that if you mix Markdown and Velocity you will experience problems using atx-style headers (prefixed with hash-marks). Instead you should use setext-style headers (underline). I was not able to find another workaround trying to escape hash-marks in velocity.

  7. [...] Maven Sites Reloaded; 2012-04-12 This is where my journey actually started when I searched for site deployment to [...]

  8. Mark Michaelis says:

    Eventually I found a solution for multi-module deployment which seems to work nice: Problem solved: Deploy Multi-Module Maven Project Site as GitHub Pages.

  9. Hi there, I found your website via Google while searching for a related topic, your website came up, it looks great.
    I have bookmarked it in my google bookmarks.

  10. Max Rohde says:

    Reblogged this on Missing Link and commented:
    Great tutorial to set up a modern Maven site to document Java projects.

  11. Great tutorial!

    I have one question: Is it possible to create a site with tabs using different menus? If so can you give me a pointer how to do that?

    TIA

  12. Roma says:

    Hi would you mind stating which blog platform you’re working with? I’m looking to start my
    own blog in the near future but I’m having a hard time choosing between BlogEngine/Wordpress/B2evolution and Drupal. The reason I ask is because your design seems different then most blogs and I’m
    looking for something unique. P.S My apologies for being off-topic but I had
    to ask!

  13. jack says:

    Thanks a lot for the tutorials, it really helped me.

  14. Perfectly written content, regards for selective information. “Necessity is the mother of taking chances.” by Mark Twain.

  15. Adelaide wedding cakes says:

    Helloi am quite fascinated by this articleI was wondering if i could promote your this article to my site only if you allow

  16. Pinterest followers says:

    i am impressed by you site, will surely put up like yours soon

  17. pinterest says:

    Some really interesting article you got hereIs this ok to email this article to our email list

  18. Sehr guter Artikel und interessantes Projekt! Weiter so!

  19. extremely interesting, many thanks so much!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 67 other followers

%d bloggers like this: