Skip to content

Problem solved: Deploy Multi-Module Maven Project Site as GitHub Pages

by on September 11, 2012

Creating Maven Sites and deploying them correctly still does not seem to be a piece of cake. Especially if you try this for multi-module projects. And if you also take the challenge to deploy the project’s site as GitHub Pages you will end up with many problems.

After some experiments I found a solution which is acceptable for me. I will not list the pains I had – only provide the solution hoping that you may find it useful:

My task:

  • I want to provide a Maven Site as GitHub Pages.
  • I want automatic deployment in Maven’s site-deploy phase.
  • I do not want snapshots deployments of the site to override released sites.
  • I want to have as little boilerplate code as possible.
  • I want to use plugins which promise to be well supported.

Last one first: I have chosen the site-maven-plugin bundled in GitHub’s maven-plugins. There are alternatives – but this one promises to be well maintained.

For Issue 22 (site plugin does not support multi-module site deployment) I found the following solution:

I read through Maven > Guide to creating a site and found this note:

If subprojects inherit the site URL from a parent POM, they will automatically append their <artifactId> to form their effective deployment location.

Having this and trying to deploy to a GH-pages subdirectory site/<version> I only had to adopt the root POM (without the need to do additional configuration in the sub-POMs):

  1. Configure <distributionManagement> as dummy to get the URL from:
        <name>Deployment through GitHub's site deployment plugin</name>
  2. Disable deployment for the maven-site-plugin (in this example you also see how to add markdown to your site):
          | allows markdown syntax for site generation. To use it place files below
          | src/site/markdown/[filename].md

    Remark: I tried many other markdown plugins but all but this one had flaws in rendering not accepting the full markdown syntax.

  3. Configure the site-maven-plugin as follows:
        <message>Creating site for ${project.artifactId}, ${project.version}</message>
        <!-- this does the trick to place every module in the correct subfolder -->

Eventually you only need to ensure the proper GitHub authentication settings in your settings.xml and setting the property in your POM accordingly as described in the Plugin’s Readme.
That’s it – despite the required GitHub authentication settings which is well described in the plugin’s ReadMe. Now I have a nice GitHub Pages Site which (in my case) has a (even nested) multi-module layout – and for now every link in every report seems to work fine.


From → Dev

One Comment
  1. Greg permalink

    Thankyou for this nice tidy complete example.

Leave a Reply

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

You are commenting using your 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