Unable the access Maven Site properties from Asciidoctor Maven Plugin

[obfischer]

The Asciidoctor Maven Plugin does not have access to the attributes for Maven Site defined in the configuration section of the Maven Site plugin. Here is an example configuration:

          <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-site-plugin</artifactId>
                <version>3.4</version>
                <inherited>true</inherited>
                <dependencies>
                    <dependency><!-- add support for ssh/scp -->
                        <groupId>org.apache.maven.wagon</groupId>
                        <artifactId>wagon-ssh</artifactId>
                        <version>1.0</version>
                    </dependency>
                    <dependency>
                        <groupId>org.asciidoctor</groupId>
                        <artifactId>asciidoctor-maven-plugin</artifactId>
                        <version>${asciidoctor.version}</version>
                    </dependency>
                    <dependency>
                        <groupId>lt.velykis.maven.skins</groupId>
                        <artifactId>reflow-velocity-tools</artifactId>
                        <version>${reflow-skin.version}</version>
                    </dependency>
                    <!-- Reflow skin requires Velocity >= 1.7  -->
                    <dependency>
                        <groupId>org.apache.velocity</groupId>
                        <artifactId>velocity</artifactId>
                        <version>1.7</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <attributes>
                        <ta>ddd</ta>
                    </attributes>
                </configuration>
            </plugin>

I can't in an Asciidoctor document now use any of there attributes while it is possible to do it when using the Maven plugin only to render Asciidoctor documents.

[mojavelinux]

@abelsromero From what you seen, is it possible to pass on this configuration?

[abelsromero]

Not that I know of, but this could be an options definetly worth looking into. Worst case scenario we just reverse engineer the whole plugin and confirm it does not work.

[obfischer]

I found a workarount. I use the resouces plugin to write all properties to a file and include this file in my documents. A workaround. A direkt access to defined attributes would be more convenient.

[mojavelinux]

@obfischer Neat workaround. I understand it's not ideal, but that at least gives us something to do to solve the problem in the meantime.

[mojavelinux]

After a lot of trial and error, I've figured out how to get access to the configuration properties from parser. Pull request on the way. This is going to open a lot of doors.

[mojavelinux]

I finally figured out how to read the Maven model from within the site parser. This enables us to read the configuration block inside the site plugin declaration and pass those options and attributes on to Asciidoctor, just like with the main plugin. (The primary difference from the main plugin is that we have to process the entire configuration ourselves).

Since the site configuration is used for other purposes, I decided to move all the configuration under the <asciidoc> element. Here's an example that shows how to set both options and attributes:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-site-plugin</artifactId>
    <version>3.3</version> <!-- 3.4 also works -->
    <configuration>
        <asciidoc>
            <templateDir>src/site/asciidoc/templates</templateDir>
            <requires>
                <require>time</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>1.5.3</version>
        </dependency>
    </dependencies>
</plugin>

You'll notice that I added excludes for AsciiDoc. This prevents the site integration from processing include files as individual pages. You can tune this pattern to your liking. There is currently no way (that I can tell) to configure this automatically.

Here's how I made it all work.

First, I use the Plexus IoC container to inject the MavenProject instance into the AsciidoctorParser class (which took me several hours to figure out, btw):

@Requirement
protected MavenProject project;

Next, I use the MavenProject to access the configuration of the site plugin (which seems to work fine with the integration test project):

project.getGoalConfiguration("org.apache.maven.plugins", "maven-site-plugin", "site", "site");

From there, we have to walk the DOM to extract information and pass it on to the Asciidoctor API.

You can refer to the integration test project to see the full setup. https://github.com/asciidoctor/asciidoctor-maven-plugin/tree/master/src/it/maven-site-plugin

This change lays the groundwork for configuring the Asciidoctor instance used by the site plugin. There may be a better way to do it. The parser may not be passing on all the necessary configuration. But it's a starting point. We can improve on it from here.

Below is a list of the features that are now available from the site plugin:

• set AsciiDoc attributes
• set Asciidoctor options
• specify a path to templates to activate and use the template converter
• enable source highlighting from the plugin configuration
• require additional Ruby libraries
• designed to be extended to make it easier to create your own site parser