Generate HTML documentation from Markdown with Maven Site plugin
Tags: java, maven, markdown, documentation
Published: 2019-12-27 14:14:12

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](https://www.sphinx-doc.org/en/master/). 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](https://maven.apache.org/doxia/references/apt-format.html), 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](https://github.com/miloszpiglas/maven-markdown-doc). 

## HTML template

Maven Site Plugin by default is using [Velocity template](https://github.com/apache/maven-doxia-sitetools/blob/master/doxia-site-renderer/src/main/resources/org/apache/maven/doxia/siterenderer/resources/default-site.vm), that is provided with [Doxia](https://maven.apache.org/doxia/index.html) (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.