Jun 172013

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 ...>

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 = '####')
    <title>Welcome to ${project.name}</title>

$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.

  One Response to “How To Use Markdown Syntax With The Maven Site Plugin”

  1. I used md5 with maven and I missed the doxia snippet macro. Fortunately Velocity makes it possible to somehow overcome of the shortage, though this is not trivial. Because of the non-triviality I created a sample project:


    that contains nothing but the documentation on how to include code from your source into your documentation using md similar way as the good old snipped macro did.

    If only I had your blog code a few month before it would have saved me a few hours of fuzzing and buzzing around with the start.


Sorry, the comment form is closed at this time.