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

  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:

    http://verhas.github.io/mdsnippet

    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.

    regards,
    Peter

Sorry, the comment form is closed at this time.