How To Use Markdown Syntax With The Maven Site Plugin

At current, there is very little information about how to use Markdown syntax to author pages for a project site with the maven-site-plugin. With this blog posting, I am going to change this - at least a little bit. ;-)

First, you should use version 3.3 of the Maven Site Plugin because it already defines a dependency on the Doxia Module Markdown, version 1.4. In your POM, add the following lines:

<project ...>
    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <artifactId>maven-site-plugin</artifactId>
                    <version>3.3</version>
                </plugin>
                ...
            </plugins>
        </pluginManagement>
        ...
    </build>
    ...
</project>

Next, in your project directory, create the directory src/site/markdown. This will host your Markdown files. Markdown files may end with a .md or .md.vm extension. In the latter case, it gets preprocessed with the Velocity template engine, so you can evaluate some macros or expressions like ${project.name} in your Markdown files.

Next, to exploit the power of the maven-site-plugin, create a file named index.md.vm in this directory. This is the start page of the project site. Note that you don’t need to create a site descriptor for this sample. Make the contents of the file look like this:

#set($h1 = '#')
#set($h2 = '##')
#set($h3 = '###')
#set($h4 = '####')
<head>
    <title>Welcome to ${project.name}</title>
</head>

$h1 Welcome to ${project.name}

Lorem ipsem dolor sit amet...

There needs to be some explanation here:

  1. Because the file ends with a .vm extension, it gets processed by the Velocity template engine. Unfortunately, Velocity uses a single hash character # as the prefix for macros and two hash characters as the prefix for comments. To escape these, I have chosen to define a variable for each heading level: $h1, $h2, etc.
  2. You sure want to define some title in an HTML head, don’t you? Unfortunately, Markdown doesn’t directly support this. However, it does support to embed HTML tags in a page. Fortunately, if the tag is <head> then the Doxia Module Markdown will put its contents into the HTML head.
  3. In a Velocity template, the maven-site-plugin supports accessing the POM via ${project.X} expressions, where X is the element you want to access. I have used this vehicle to quote the project name in the HTML title and level one heading of the document.

Finally, to start your sample site, run the following command …

$ mvn site:run

… and point your browser to http://localhost:8080 to see the magic happening.

Enjoy!