How do I enable tabs in Asciidoc and Maven with asciidoctor-tabs and asciidoctor-maven-plugin?

Question

In the asciidoctor-maven-plugin, I can add extensions, but I need to specify a GAV and classname.

How do I add the asciidoctor-tabs extension to enable tabs in adoc files?

As far as I can tell, the tabs functionality might not exist on Maven Central.

Answer 1

Looks like this extension is written in node. Are you sure this is intended to be used from maven?

Actually, asciidoctor/asciidoctor-tabs is written in Ruby, which complicates its direct use with Maven.

+---------------------+        +------------------------+
| asciidoctor-tabs    |        | asciidoctor-maven-     |
| (Ruby Extension)    |  --->  | plugin (Maven Project) |
+---------------------+        +------------------------+

You might need to run that extension within a JRuby environment, which means creating a custom script that utilizes JRuby to run the asciidoctor-tabs extension.

You might consider creating a custom Maven plugin that invokes this script during your build process. That plugin can be configured to execute the JRuby script as part of the Maven build lifecycle.
Make sure all necessary dependencies, including JRuby and the asciidoctor-maven-plugin, are correctly set up in your pom.xml.

Then configure the asciidoctor-maven-plugin in your pom.xml to include the custom script or Maven plugin you created, ensuring it is executed at the right phase of the build lifecycle.

---

A pom.xml file would include the asciidoctor-maven-plugin and a possible custom script or plugin for handling the Asciidoctor Tabs extension.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <groupId>your.group.id</groupId>
    <artifactId>your-artifact-id</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>Your Project Name</name>

    <properties>
        <asciidoctor.maven.plugin.version>2.2.4</asciidoctor.maven.plugin.version>
        <!-- Other properties -->
    </properties>

    <build>
        <plugins>
            <!-- Asciidoctor Maven Plugin -->
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>${asciidoctor.maven.plugin.version}</version>
                <executions>
                    <execution>
                        <id>generate-docs</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <!-- Add your configuration here -->
                        </configuration>
                    </execution>
                </executions>
            </plugin>

            <!-- Custom Script/Plugin for Asciidoctor Tabs -->
            <!-- That is an example. You would need to create a custom plugin or script to handle this. -->
            <plugin>
                <groupId>your.custom.plugin.groupId</groupId>
                <artifactId>your-custom-plugin-artifactId</artifactId>
                <version>your-plugin-version</version>
                <executions>
                    <execution>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>your-custom-goal</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

            <!-- Other plugins if necessary -->
        </plugins>
    </build>

    <dependencies>
        <!-- Add your project dependencies here -->
    </dependencies>

</project>

That pom.xml is a starting point.

your-custom-plugin-artifactId would refer to a custom Maven plugin you would need to create to handle the Asciidoctor Tabs extension. You would implement a Maven Mojo (Maven plain Old Java Object) that defines your plugin's goal. Inside the Mojo, write Java code to invoke JRuby and run the asciidoctor-tabs Ruby script. You will need to pass the relevant Asciidoc files to the script.