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.