Using Json data with the maven-site-plugin

Posted: February 22, 2020 in Uncategorized
Tags: , ,

The maven-site-plugin allows for documentation websites to be created for maven projects.  Developers write their documentation in a variety of documentation formats such as markdown and the plugin translates this to HTML.

The maven site plugin supports generating documentation based on Velocity templates.  This allows for the actual contents for the documentation to be generated at build time based on a template. It is sometimes handy to use Json data in this template. This allows for your site to render data based on Json files in your project that might be used for other things.  This is supported by the maven-site-plugin but getting this to work requires enabling the velocity JsonTool module.

Create a Plugin that enables Json Tool

The org.apache.velocity.tools:velocity-tools-generic package supports JSON parsing but the JSON support is not turned on by default.  Turning this on requires adding data to the site-tools.xml file.  To get this to work I had to create by own plugin that depended on the org.apache.velocity.tools:velocity-tools-generic package but also added in a site-tools.xml. It seems that including the site-tools.xml directly in my site project without using a secondary plugin doesn’t expose the site-tools.xml to the classpath at build time.

The pom file for this plugin should contain the following

<groupId>info.ssinger.jsontemplate</groupId>
<artifactId>plugin</artifactId>
<version>1.0.0</version> 
<packaging>jar</packaging>
<name>plugin</name>
 <build>
   <plugins>
     <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-plugin-plugin</artifactId>
       <version>3.2</version>
       <configuration>
        <skipErrorNoDescriptorsFound>true</skipErrorNoDescriptorsFound
      </configuration>
     </plugin>
     <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-site-plugin</artifactId>
       <version>3.8.2</version>
       <configuration>
         <skip>true</skip>
       </configuration>
     </plugin>
   </plugins>
 </build>

We are adding in the maven-plugin-plugin since we are building a maven plugin.

We also add in a section for the maven-site-plugin with <skip> set to true in the configuration. This is because the plugin is a sub-module of our main site project but we haven’t provided a site for the plugin itself.

Add a velocity-tools dependency

The plugin/pom.xml file also needs a dependency (in the normal dependencies section, not the build portion) of the pom file to include the org.apache.velocity.tools:velocity-tools jar. This jar contains the actual JsonTool support.

 <dependencies>
        <dependency>
          <groupId>org.apache.velocity.tools</groupId>
          <artifactId>velocity-tools-generic</artifactId>
          <version>3.0</version>
        </dependency>
    </dependencies>

Add site-tools.xml file

Next we add in a src/main/resources/META-INF/maven/site-tools.xml file to the project. This file will actually add the JsonTool to the toolbox.

<?xml version="1.0" encoding="UTF-8"?>
 <!-- Add custom tools to Velocity tools. The tools.xml file is included in the classpath and Velocity finds it. --> 
<tools> 
  <toolbox scope="application"> 
    <tool class="org.apache.velocity.tools.generic.JsonTool" />
  </toolbox> 
</tools>

The the above two steps will create our plugin (named plugin) that enables the JsonTool

Update the site pom.xml

The pom.xml file of our site(this is the top-level pom.xml in our sample project) now needs some changes to include the plugin.

Add the plugin to the site pom file

The site pom.xml file for our maven-release site needs to include the plugin that we created above.  We define the plugin as as submodule in our sites pom.xml file.

<modules>
  <module>plugin</module>
</modules>

Alternatively we could have built our plugin completely independently.

Next we add in the plugin as a dependency of the maven-site-plugin.

<build>
 <plugins>
   <plugin>
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-site-plugin</artifactId>
     <version>3.8.2</version>
     <dependencies>
       <dependency>
         <groupId>info.ssinger.jsontemplate</groupId>
         <artifactId>plugin</artifactId>
         <version>1.0.0</version>
       </dependency>
     </dependencies>
   </plugin>
 </plugins>
</build>

Create Json File

We next create a Json file in our site.  I create mine in src/site/markdown/data.json but this could live under src/main/resources or elsewhere.

{ 
  "item1": "First Item", 
  "item2": "Second Item",
  "item3": "Third Item"
}

Create markdown Template

Now we write a markdown velocity template that uses our Json data.  Files in the release site that end in the .vm extension will be treated as velocity templates.

src/site/markdown/page.md.vm

#set($data=$json.read('src/site/markdown/data.json'))
|Item|Description|
|----|-----------|
#foreach ($item in $data.keys()) 
|$item|$data.get($item)|
#end

The first line  parses the Json file into a variable called data

Then we loop through the items in this parsed Json object to create a table.

Build the Site

mvn package site

will create the plugin and the site

Complete Example

The complete example is available at github

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s