Generate HTML documentation from Markdown with Maven Site plugin

Preparing readable documentation, that is easy to maintain is not a trivial task and not a favourite one for most developers. We have great choice of methods for creating documentation, from simple ones, like plain text files, up to more sophisticated like Sphinx generator. Each of them has its own advantages and drawbacks. Plain files are easy to maintain, doesn't require any special files, but doesn't fit to modern web. On the other hand Sphinx is advanced solution for preparing professional documentation, but require 3-rd party tools.

For Java developers, that use Apache Maven for building projects, it will be most convenient to use same tool for generating documentation. In site lifecycle phase Maven runs Site plugin, which generate documentation from source files. Output HTML site is useful in many cases, but it is not very user friendly. By default source files must be saved in APT format, although nowadays we rather use Markdown or reStructuredText.

Fortunately maven-site-plugin allows some customization, which we use in order to generate simple documentation site from markdown files. Example project might be found on Github.

HTML template

Maven Site Plugin by default is using Velocity template, that is provided with Doxia (framework internally used by Maven for content generation). For our purpose we need something simpler, so we prepare new template and save it as dev-to-template.vm in src/site/ directory.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
  </head>
  <body>
    <a href="index.html">Start</a>
    #*   *#$bodyContent
  </body>
</html>

Variable $bodyContent references to output from rendering Markdown files, that must be saved in directory src/site/markdown.

Module configuration

We need to adjust configuration of maven-site-plugin in module pom.xml

<plugin>
  <artifactId>maven-site-plugin</artifactId>
  <version>3.8.2</version>
  <configuration>
    <generateReports>false</generateReports>
    <templateFile>src/site/dev-to-template.vm</templateFile>
    <relativizeDecorationLinks>false</relativizeDecorationLinks>
  </configuration>
  <dependencies>
    <dependency>
      <groupId>org.apache.maven.doxia</groupId>
      <artifactId>doxia-module-markdown</artifactId>
      <version>1.9</version>
    </dependency>
   </dependencies>
 </plugin>

With property templateFile we point to created template file. When plugin has dependency on doxia-module-markdown it will search for Markdown files in directory src/site/markddown and use it for generating HTML markups.

Content generation is triggered with command ./mvnw site and HTML output is saved in directory target/site/. With example template we get HTML documentation with simple navigation. If there is a need it should be easy to add more customization. What is most important we don't need any extra tools for generating content.

Blog

Generate HTML documentation from Markdown with Maven Site plugin

Miłosz Pigłas

HTML template

Module configuration

Join Our Newsletter. No Spam, Only the good stuff.

Related