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:
    <distributionManagement>
      <site>
        <id>github-pages-site</id>
        <name>Deployment through GitHub's site deployment plugin</name>
        <url>site/${project.version}</url>
      </site>
    </distributionManagement>
    
  2. Disable deployment for the maven-site-plugin (in this example you also see how to add markdown to your site):
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-site-plugin</artifactId>
      <version>3.1</version>
      <dependencies>
        <dependency>
          <!--
          | allows markdown syntax for site generation. To use it place files below
          | src/site/markdown/[filename].md
          -->
          <groupId>org.apache.maven.doxia</groupId>
          <artifactId>doxia-module-markdown</artifactId>
          <version>1.3</version>
        </dependency>
      </dependencies>
      <configuration>
        <skipDeploy>true</skipDeploy>
      </configuration>
    </plugin>
    

    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:
    <plugin>
      <groupId>com.github.github</groupId>
      <artifactId>site-maven-plugin</artifactId>
      <version>0.7</version>
      <configuration>
        <message>Creating site for ${project.artifactId}, ${project.version}</message>
        <!-- this does the trick to place every module in the correct subfolder -->
        <path>${project.distributionManagement.site.url}</path>
        <merge>true</merge>
      </configuration>
      <executions>
        <execution>
          <id>github-site</id>
          <goals>
            <goal>site</goal>
          </goals>
          <phase>site-deploy</phase>
        </execution>
      </executions>
    </plugin>
    

Eventually you only need to ensure the proper GitHub authentication settings in your settings.xml and setting the property github.global.server 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.

Links

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:

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