Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 41 ยท Lifecycle and Plugins

Documents with Maven: Asciidoctor and Apache POI

Generate HTML or PDF documentation from AsciiDoc with the Asciidoctor Maven plugin, create PowerPoint files with Apache POI, and run the code from Maven with exec.

Maven is mostly described in terms of compiling and packaging code, but the same machinery, dependencies for libraries and plugins for build-time work, covers other jobs too. Two examples show the two halves of the system clearly:

  • A plugin that turns documentation written in text files into HTML or PDF during the build (the Asciidoctor Maven plugin).
  • A library dependency that lets your program create Office files such as a PowerPoint presentation (Apache POI).

Neither will run on this site, because the site has no Maven and no file system to produce documents. So the XML and Java that call real libraries are read-only, and the runnable example is a Java stand-in that does a miniature version of what Asciidoctor does: reads a small text document and produces HTML. The versions shown are examples; check Maven Central for current ones.

Plugin or dependency?

The difference decides where the declaration goes (see Plugins and Goals and Adding Dependencies):

Plugin Dependency
Where <build><plugins> <dependencies>
Runs During the build, in a lifecycle phase Inside your program, at run time
Example Asciidoctor: turns .adoc into HTML POI: your code calls XMLSlideShow
On the classpath of Maven itself Your application

Documentation from AsciiDoc

AsciiDoc is a plain-text markup for technical documentation, similar in spirit to Markdown but richer: tables of contents, includes, admonitions, callouts and cross-references. Asciidoctor is the processor that converts it to HTML, PDF, DocBook and other formats. Because the documents are text files in the repository, they can be reviewed in pull requests, versioned with the code and built by CI, which keeps docs from rotting.

A small document, src/docs/asciidoc/index.adoc (read-only):

ASCIIDOC
= Shop API Guide
:toc:

== Overview

The Shop API manages *products* and _orders_.

== Endpoints

* GET /products
* POST /orders

NOTE: All requests need a bearer token.

Add the plugin to the pom.xml:

XML
<build>
  <plugins>
    <plugin>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctor-maven-plugin</artifactId>
      <version>3.1.1</version>
      <executions>
        <execution>
          <id>docs-html</id>
          <phase>generate-resources</phase>
          <goals>
            <goal>process-asciidoc</goal>
          </goals>
          <configuration>
            <sourceDirectory>src/docs/asciidoc</sourceDirectory>
            <outputDirectory>${project.build.directory}/generated-docs</outputDirectory>
            <backend>html5</backend>
            <attributes>
              <project-version>${project.version}</project-version>
            </attributes>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Read it as a sentence: "during the generate-resources phase, run the process-asciidoc goal of the Asciidoctor plugin, taking sources from src/docs/asciidoc and writing HTML to target/generated-docs". Run mvn generate-resources (or any later phase such as package) and the HTML appears. Because the phase is bound in the POM, the docs are built whenever the project is built, so a broken include or a missing file fails the build early (see Lifecycles and Phases).

Useful variations:

  • Attributes pass Maven values into the text, so {project-version} in the document prints the real version.
  • A second <execution> with <backend>pdf</backend> produces a PDF; PDF output needs the asciidoctorj-pdf dependency added to the plugin.
  • Includes (include::../../main/java/.../Example.java[tags=snippet]) pull code from real, compiled files, so examples in the docs cannot go out of date.
  • The generated HTML can be copied into the packaged artifact (for instance into a Spring Boot static folder) with the Resources plugin, or published to a site.

Office files with Apache POI

Apache POI is a Java library for reading and writing Microsoft Office formats. For the modern formats (.xlsx, .docx, .pptx) you depend on poi-ooxml, which brings poi and the other pieces it needs as transitive dependencies (see Transitive Dependencies and Mediation):

XML
<dependencies>
  <dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi-ooxml</artifactId>
    <version>5.4.0</version>
  </dependency>
</dependencies>

Run mvn dependency:tree to see everything it pulls in, such as XML beans, compression and logging libraries. POI logs through Log4j's API, so add a logging implementation or accept the default no-op behavior.

A program that creates a one-slide presentation (read-only, since it needs the library and writes a file):

Java
import java.awt.geom.Rectangle2D;
import java.io.FileOutputStream;
import java.io.IOException;
import org.apache.poi.xslf.usermodel.*;

public class MakeSlides {
    public static void main(String[] args) throws IOException {
        try (XMLSlideShow deck = new XMLSlideShow();
             FileOutputStream out = new FileOutputStream("target/hello.pptx")) {

            XSLFSlide slide = deck.createSlide();
            XSLFTextBox box = slide.createTextBox();
            box.setAnchor(new Rectangle2D.Double(60, 60, 600, 100));
            box.setText("Hello from Maven and POI");

            deck.write(out);
        }
    }
}

The try with resources closes the show and the file for you. The same library family offers XSSFWorkbook for Excel and XWPFDocument for Word.

Running it from Maven

To run a main method as part of a build without packaging, use the Exec plugin:

Terminal
mvn compile exec:java -Dexec.mainClass=MakeSlides

If you want it to run automatically during the build, bind the exec:java goal to a phase in the POM, as you did for Asciidoctor. Remember that anything run at build time needs the dependencies on the plugin's classpath, which exec:java provides from your project.

What a documentation plugin does, in miniature

The processor reads text, recognizes simple structures and emits markup. Here is a deliberately tiny stand-in written in Java: it understands a title (= ), section headings (== ), bullet lists (* ), paragraphs and *bold* text, and prints HTML. It is not Asciidoctor, which implements a far larger language, but it shows the mapping from lines to elements.

Java A miniature AsciiDoc converter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

A build plugin is therefore a program Maven calls with paths and settings: it reads sourceDirectory, writes into outputDirectory, and reports success or failure. If you want to write such a program yourself, see Writing a Simple Maven Plugin.

Tips for document builds

  • Keep generated files under target/ and never commit them; regenerate them in CI.
  • Pin plugin versions (see Plugins and Goals) so documentation builds are reproducible.
  • Build docs in a separate profile if they are slow, and enable it in CI (see Profiles and Environments).
  • For Office output, never hard-code file paths; write to target/ or take a path from a system property.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where do you declare the Asciidoctor Maven plugin?

    It works at build time, so it is a plugin; libraries your program calls are dependencies.
  2. 2. What does binding process-asciidoc to the generate-resources phase mean?

    Phases run in order, so any lifecycle command that reaches generate-resources triggers the goal.
  3. 3. Which dependency gives you modern Office formats such as .pptx in Apache POI?

    poi-ooxml covers the XML-based formats and brings the core poi module transitively.
  4. 4. How can you see all libraries that poi-ooxml pulls in?

    The dependency tree lists direct and transitive dependencies with versions.

Summary

  • Plugins do build-time work in lifecycle phases; dependencies are libraries your program calls. Choose the matching section of the POM.
  • The Asciidoctor plugin binds process-asciidoc to a phase and turns .adoc sources into HTML or PDF under target/; attributes and includes keep docs in sync with the code.
  • Apache POI (poi-ooxml) creates and reads Office files from Java; mvn dependency:tree shows what it brings in.
  • Run a main class from Maven with exec:java, or bind it to a phase.
  • Pin versions, keep generated output out of Git and use profiles for slow documentation builds.

Next: The Command Line Toolbox.