Asciidoctor Parser Doxia Module

This module is considered in Beta, available for general use covering most AsciiDoc features. Please, consider sharing feedback and reporting any issue you find, or improvement you consider to help us improve.

This module uses Asciidoctor to parse AsciiDoc source files and then uses a custom converter adapted to Maven Site styles. Compatibility is being validated with the default skin and specially Fluido skin.

This module should be used by those desiring a simple out-of-the-box experience and willing to sacrifice some AsciiDoc features (for now). See Supported AsciiDoc elements below for details on support.

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.21.0</version>
            <dependencies>
                <dependency> <!-- Add Asciidoctor Doxia Module -->
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-parser-doxia-module</artifactId>
                    <version>3.1.1</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.

Since maven-site-plugin v3.20.0, paths apply a default locale configuration. If locale is not set, sources must be places in src/site/en/asciidoc/.

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

Given the modules implements a custom converter, the following features are limited:

  • templateDirs configurations are not supported in this module.

  • Extensions injected with requires can only modify the AST. Modifications of output won’t be applied.

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 internal AsciiDoc files (i.e., files and folders 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.21.0</version>
    <configuration>
        <asciidoc>
            <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-parser-doxia-module</artifactId>
            <version>3.1.1</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).
    requires

    Same as the plugin’s requires, but with the consideration that only extensions that add elements to the Asciidoctor AST can be used.
    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.

    Since v3.1.0+ the source filename will be displayed alongside issues found during conversion.

Supported AsciiDoc elements

This module is still under development, here is a summary of supported features:

  • Document Title, present in page

  • Document preamble

  • Section titles from 1 to level 5

    • Support for sectnums and sectnumlevels

  • Paragraphs

    • Basic formatting (bold, italics, monospace, etc.)

    • Attributes substitutions

  • Lists

    • Unordered, for * and - markers

    • Ordered, only arabic numerals

    • Description lists, with nested ordered, unordered and description lists

    • Formatted text in list items

      Unlike in Asciidoctor lists, descriptions are not surrounded by <p> and list themselves are not surrounded by <div> elements.

  • Code blocks with source-highlighting using Fluido Skin Pretiffy.

    • Support for numbered lines with linenums

    • Support for AsciiDoc titles

  • Examples

  • Literal blocks

  • Quotes

  • Tables

    • With and without headers

    • Non-nested tables with basic layouts

    • Basic formatting inside tables (bold, italics, etc.)

  • Images, both as block and inline

  • Captions in elements listed above