Using Markdown with the Maven site plugin

I find that generating Maven project documentation is always a bit cumbersome with the default XDOC or APT (“Almost Plain Text”) syntaxes. This probably has to do with getting accustomed to using Markdown while doing my thing on GitHub, which is sort of the de facto standard there.

While writing some documentation for a new Hippo CMS plugin the other day I noticed that the maven site plugin already supports the Markdown syntax and it’s actually quite easy to setup, but the markdown-doxia-module documentation is a bit limited. With this post I hope shed some more light and help you get going with using Markdown for writing documentation.

First up we need to define the maven-site-plugin in our project pom.xml file. If you start with version 3.3 the markdown-doxia-module will already be included. However for this post I will use the latest version ( at this moment 1.5 ), so I have to define it explicitly in my POM file.

<plugins>
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>3.3</version>
    <dependencies>
      <dependency>
        <groupId>org.apache.maven.doxia</groupId>
        <artifactId>doxia-module-markdown</artifactId>
        <version>1.5</version>
      </dependency>
    </dependencies>
  </plugin>
</plugins>

Next, we will need to create the directory src/site/markdown which will hold our Markdown files. Make sure the files have the .md extension.

Now let’s start with a simple file called index.md that needs to go into the markdown folder. To prove that it will render markdown syntax we can use the following snippet as content.

A First Level Header
====================
A Second Level Header
---------------------
Now is the time for all good men to come to
the aid of their country. This is just a
regular paragraph.

The quick brown fox jumped over the lazy
dog's back.

### Header 3
> This is a blockquote.>
> This is the second paragraph in the blockquote.
>

## This is an H2 in a blockquote

Now start the maven-site-plugin from the command-line:

$ mvn site:run

and point your browser to http://localhost:8080/ and see the beautiful result!

A concrete implementation can be found on the Hippo forge.

Leave a Reply