Documentation Maven Plugin

Introduction

The Markdown Docs Maven Plugin is used to generate HTML pages (like this one) from markdown source files. It is intended to facilitate the maintenance of documentation artifacts stored within the codebase, as Markdown. The plugin performs a series of tasks that convert the Markdown into HTML pages that can be deployed alongside your code (or wherever you choose).

Purpose

The goal of the plugin is to allow teams to create documentation that is both beautiful and maintainable.

We believe that documentation artifacts work best when stored as part of a project's source control. This allows code lifecycle processes, like pull requests, to be extended to documentation, helping teams ensure that documentation updates happen alongside the code changes that necessitate them.

Repository-based documentation is best stored as flat files, in order to make changes visible from file diffs. However, the end result is often less beautiful and usable than a PDF or webpage. This plugin seeks to bridge that gap, allowing teams to maintain flat files in the repository, and then transform them into rich documentation artifacts via a series of configurable build steps.

Usage

Goals

The plugin exposes 4 Maven goals:

Markdown to HTML

The markdown-to-html goal takes markdown files from a source directory, and generates corresponding HTML files in the target directory. Although only body content is generated from the Markdown, the goal allows the specification of header and footer HTML fragment files. These fragments can specify CSS, JS, and static assets.

Copy Frontend Artifacts

The copy-frontend-artifacts goal copies static artifacts into the target directory for use by the generated HTML pages.

Transform HTML

The transform-html goal applies a series of transformers to HTML documents. This allows the addition of structure to the plain content markup generated by the markdown-to-html goal. As an example, com.icfnext.documentation.plugin.html.IcfNextTransformer was used to create the header, footer, and left rail shown on this page.

Add Table of Contents

The add-table-of-contents plugin scans HTML documents for headings, and generates markup for a table of contents, which is then inserted into the document.

Configuration

Shared Properties

The following configurations are shared between all goals.

Property	Type	Required	Default	Description
`baseDir`	String (path)	`true`	-	The directory in which the plugin will scan for files.When generating HTML from markdown, this will generally be under `src`, whereas subsequent steps will generally be under `target`.
`failOnError`	boolean	`false`	`true`	Whether the plugin should halt the build if a (recoverable) error is encountered.
`recursive`	boolean	`false`	`true`	Whether to continue search for applicable files inside any directories encountered under the `baseDir`
`outputDir`	String (path)	`false`	`${project.outputDirectory}`	The directory into which files should be written. When `recursive` = `true`, output files will be placed relative to their corresponding input files

Markdown to HTML

Property	Type	Required	Default	Description
`fixMarkdownLinks`	boolean	`false`	`true`	If true, when generating HTML from Markdown, any links to local Markdown files will be adjusted to point to the corresponding HTML file.
`fileMask`	String	`false`	`*.md`	A filter specifying which files should be converted to HTML
`headerHtmlFile`	String (path)	`false`		Specifies a file to include before the generated content in the output HTML. At minimum, this file should include the opening `html` and `body` tags.
`footerHtmlFile`	String (path)	`false`		Specifies a file to include after the generated content in the output HTML. At minimum, this file should include the closing `body` and `html` tags.

Copy Frontend Artifacts

Property	Type	Required	Default	Description
`fileMask`	String	`false`	`*`	A filter specifying which files should be copied

Transform HTML

Property	Type	Required	Default	Description
`transformers`	List<String>	true	-	A list of classes implementing the `com.icfnext.docs.plugin.html.HtmlTransformer` interface. The `transform` method on this class takes a JSoup `Document` object, which it can transform as needed. Once all specified transformers have been called, the document will be written back to the file system.

Add Table of Contents

Property	Type	Required	Default	Description
`excludeH1`	boolean	false	true	Whether H1 should be excluded to the ToC
`LevelsToInclude`	int	false	3	How many heading levels should be included in the ToC
`targetSelector`	String	false	"nav"	A CSS selector used to locate the element into which the ToC markup will be inserted
`title`	String	false	-	The title text to insert before the ToC markup (e.g., "Contents")
`titleTag`	String	false	"h4"	The tag used to wrap the title (used only when `title` is supplied).

Example Usage

Example usage can be found in the documentation-maven-plugin-documentation module (which generated this page). The plugin is configured with a separate execution for each of the goals.

  <build>
    <plugins>
      <plugin>
        <groupId>com.icfnext.documentation</groupId>
        <artifactId>documentation-maven-plugin</artifactId>
        <version>1.0.0-SNAPSHOT</version>

        <configuration>
          <baseDir>target/html</baseDir>
          <outputDir>target/html</outputDir>
        </configuration>

        <executions>
          <execution>
            <id>generate-html</id>
            <phase>process-resources</phase>
            <goals>
              <goal>markdown-to-html</goal>
            </goals>
            <configuration>
              <baseDir>docs</baseDir>
              <headerHtmlFile>${project.basedir}/src/main/resources/header.html</headerHtmlFile>
              <footerHtmlFile>${project.basedir}/src/main/resources/footer.html</footerHtmlFile>
            </configuration>
          </execution>
          <execution>
            <id>copy-frontend-artifacts</id>
            <phase>process-resources</phase>
            <goals>
              <goal>copy-frontend-artifacts</goal>
            </goals>
            <configuration>
              <baseDir>src/main/resources/static</baseDir>
            </configuration>
          </execution>
          <execution>
            <id>transform-html</id>
            <phase>process-resources</phase>
            <goals>
              <goal>transform-html</goal>
            </goals>
            <configuration>
              <transformers>
                <transformer>com.icfnext.documentation.plugin.html.IcfNextTransformer</transformer>
              </transformers>
            </configuration>
          </execution>
          <execution>
            <id>add-toc</id>
            <phase>process-resources</phase>
            <goals>
              <goal>add-table-of-contents</goal>
            </goals>
            <configuration>
              <title>Contents</title>
              <levelsToInclude>2</levelsToInclude>
            </configuration>
          </execution>
        </executions>

        <dependencies>
          <dependency>
            <groupId>com.vladsch.flexmark</groupId>
            <artifactId>flexmark-all</artifactId>
            <version>0.50.40</version>
          </dependency>
          <dependency>
            <groupId>org.jsoup</groupId>
            <artifactId>jsoup</artifactId>
            <version>1.12.1</version>
          </dependency>
          <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>28.1-jre</version>
          </dependency>
        </dependencies>
      </plugin>
    </plugins>
  </build>