Setup & Configuration

Setup

To author your Maven-generated site in AsciiDoc, you must first add a dependency on the Asciidoctor plugin to your maven-site-plugin declaration (which more precisely adds a Doxia Parser Module).

Maven site integration

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.12.1</version>
            <dependencies>
                <dependency> <!-- Add Asciidoctor Doxia Parser Module -->
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-maven-plugin</artifactId>
                    <version>2.2.4</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

You can find a full example in the Asciidoctor Maven examples project.

The Asciidoctor Doxia module follows the maven-site-plugin conventions for file location, and delegates all resource management to it.

First, all of your AsciiDoc-based files should be placed in src/site/asciidoc with an extension of .adoc. These files will be converted into the target/site directory. For example, the file src/site/asciidoc/usage.adoc will be converted into target/site/usage.html.

Then, all resources (images, css, etc.) should be placed in src/site/resources. These will be automatically copied into target/site.

Also, note that AsciiDoc files are converted to embeddable HTML and inserted into the site’s page layout. This disables certain features such as the sidebar toc.

Make sure you add a menu item for each page so you can access it from the site navigation:

site.xml

<body>
    ...
    <menu name="User guide">
        <item href="usage.html" name="Usage" />
    </menu>
    ...
</body>

Configuration

As of version 1.5.3 of the plugin, you can configure Asciidoctor by specifying configuration properties in the plugin declaration, just like with the other goals of the plugin. There are two important differences, however.

All the configuration for Asciidoctor in the site integration must be nested inside an <asciidoc> element. This is necessary since the <configuration> element is used to configure more than just the Asciidoctor integration.

Here’s an example that shows how to set options, attributes and ignore partial AsciiDoc files (i.e., files that begin with an underscore).

Maven site integration with Asciidoctor configuration

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>3.12.1</version>
    <configuration>
        <asciidoc>
            <templateDirs>
                <dir>src/site/asciidoc/templates</dir>
            </templateDirs>
            <requires>
                <require>asciidoctor-diagram</require>
            </requires>
            <attributes>
                <source-highlighter>coderay</source-highlighter>
                <coderay-css>style</coderay-css>
            </attributes>
        </asciidoc>
        <moduleExcludes>
            <asciidoc>**/_*.adoc</asciidoc>
        </moduleExcludes>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctor-maven-plugin</artifactId>
            <version>2.2.4</version>
        </dependency>
    </dependencies>
</plugin>

The Asciidoctor base directory (i.e., document root) is configured as src/site/asciidoc by default, though this can be overridden. To do so, you can use either maven-site-plugin siteDirectory or Asciidoctor baseDir configuration options. Note that the first will affect the default resources directory also.

You’ll notice in the example that excludes have been added for certain AsciiDoc files. This prevents the site integration from processing partial files (i.e., includes) as individual pages. You can tune this pattern to your liking. There’s currently no way (that we can tell) to configure this automatically.

Not all options found in the asciidoctor-maven-plugin are available in the <asciidoc> element. This is for simplicity and restrictions in how maven-site-plugin manages resources.

The supported ones are:

baseDir

Same as the plugin’s baseDir. Sets the root path for resources. Not set by default, AsciiDoc documents will be searched in src/site/asciidoc. External resources should be located in src/site/resources.

Consider using maven-site-plugin’s siteDirectory instead for better integration with the site functions (ie. resource copying).

templatesDirs (also template_dirs)

Built-in templates are supported by specifying one or more template directories. This feature enables you to provide custom templates for converting any node in the tree (e.g., document, section, listing, etc). Custom templates can be extremely helpful when trying to customize the appearance of your site. Each path to add should be enclosed in a <dir> element.

requires

Same as the plugin’s requires.
Specifies additional Ruby libraries not packaged in AsciidoctorJ, empty by default.

attributes

Similar to the plugin’s attributes.
Allows defining a set of Asciidoctor attributes to be passed to the conversion.
In addition to attributes set in this section, Maven properties are also passed as attribute (replacing . by - in the name). These include those defined in the <properties> section of the project, parent projects and the user’s settings.xml.

<properties>
  <my-site.version>2.3.0</my-site.version> (1)
</properties>

1	Will be passed as `my-site-version` to the converter.

logHandler

Enables processing of Asciidoctor messages. For example to hide them, enable finer detail or fail the build on certain scenarios (e.g. missing included files). To see all options refer to the main plugin logHandler configuration.

Due to limitations in how Maven site integration works, it is not possible to provide the filename in the error message. We are aware this is not ideal and are tracking any development on the Maven side towards this goal (DOXIA-555).