25 March 2014

Maven Site using Markdown

I like Markdown. It is a popular lightweight markup language, easy to read and easy to write. It is supported by many websites and text editors (and recently got standardised). I use it since many years and whenever I take notes, even in Notepad or on my mobile phone, I structure my text using at least I use * to list items and --- to separate paragraphs. Recently when I had to publish some documentation for a project, I was not surprised to find my existing notes in Markdown. So why not generate the final document from them?

Newley Marked Down Misspelled Sale Sign FailApache Maven can be used to build a project site. If you are a Java developer you probably have seen some of these sites already. But the auto generated Maven reports are not much use if you want to add real documentation. The recommended formats to create content are APT or Xdoc. While the APT format is similar to Markdown, I did not want to convert my documents and went off tweaking Doxia for Markdown. This took me extra two hours, but hey - work is supposed to be fun sometimes too, right?

Maven Doxia is the content generation framework used by the site plugin. It supports Markdown since Doxia 1.3. The site content is separated by format and Markdown files need to be inside a markdown folder and named *.md.
project
|-- pom.xml
`-- src
    |-- main
    |-- test
    `-- site
        |-- markdown
        |   `-- Readme.md
        `-- site.xml
To enable markdown processing in Maven site the doxia-module-markdown has to be added to your pom.xml.
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-site-plugin</artifactId>
      <version>3.2</version>
      <dependencies>
        <!-- add optional Markdown processor -->
        <dependency>
            <groupId>org.apache.maven.doxia</groupId>
            <artifactId>doxia-module-markdown</artifactId>
            <version>1.4</version>
        </dependency>
      </dependencies>
    </plugin>
  </plugins>
</build>
During mvn site all Markdown files are translated to HTML and put into the target/site folder. To add them to the menu of the generated site, you have to add links to the decoration descriptor of Doxia, also known as site.xml.
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/DECORATION/1.4.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/DECORATION/1.4.0
                        http://maven.apache.org/xsd/decoration-1.4.0.xsd">

    <body>
        <menu name="Documents">
            <item name="Readme" href="Readme.html" />
        </menu>

        <menu ref="reports" />
    </body>

</project>
Done. Success. Profit. ;-)