Asciidoctor Converter Doxia Module

This module uses Asciidoctor to directly convert sources without additional customizations. That means you will get the same HTML as using Asciidoctor but some elements may not be well presented due to incompatibilities with Doxia Skins.

This module should be used by:

  • Users interested in full AsciiDoc support and willing to work con custom CSS styles or custom templates.

  • Those already using asciidoctor-maven-plugin v2 or prior module since this offers the same functionality.

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.

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 Module -->
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-converter-doxia-module</artifactId>
                    <version>3.0.0</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.

  1. 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-converter-doxia-module</artifactId>
            <version>3.0.0</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.

  2. 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).