Fix: Asciidoctor Plugin Not Working On Linux

Dec 3, 2025 by Alex Johnson 45 views

Troubleshooting Asciidoctor Plugin Issues on Linux

Are you encountering issues with the Asciidoctor plugin while working in a Linux environment? This comprehensive guide addresses the common problem of the Asciidoctor plugin failing to function correctly under Linux, offering solutions and workarounds to get your documentation process back on track. We'll delve into the specifics of the error, the configuration details, and the steps you can take to resolve it. If you're struggling with this issue, you're in the right place. Let's explore the problem and its solutions in detail.

Understanding the Problem: Asciidoctor Plugin Failure on Linux

When working with documentation, the Asciidoctor Maven plugin is a powerful tool for converting AsciiDoc files into various formats, such as HTML and PDF. However, users sometimes encounter a frustrating issue where the plugin functions perfectly fine under Windows but fails to work as expected in a Linux environment. This discrepancy often stems from dependency conflicts or missing components specific to the Linux operating system. Let's begin by understanding the specific error encountered, which often points to missing JRuby components or issues with loading Asciidoctor itself. We will explore the root cause of this problem and then present targeted solutions to resolve it. To understand the issue better, we need to examine the configuration details and the error messages that arise when the plugin fails under Linux.

Configuration Details

The user in question has configured the Asciidoctor Maven plugin within their pom.xml file, utilizing Maven version 3.9.11 and Java 17. Here’s a snippet of the relevant configuration:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>3.2.0</version>
    <executions>
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <sourceDirectory>src/site/asciidoc</sourceDirectory>
                <backend>xhtml5</backend>
                <attributes>
                    <toc>left</toc>
                </attributes>
                <requires>
                    <require>asciidoctor-diagram</require>
                </requires>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>2.3.23</version>
        </dependency>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-diagram</artifactId>
            <version>3.0.1</version>
        </dependency>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-diagram-plantuml</artifactId>
            <version>1.2025.3</version>
        </dependency>
    </dependencies>
</plugin>

This configuration specifies the use of Asciidoctor Maven plugin version 3.2.0, with the goal of processing AsciiDoc files during the generate-resources phase of the Maven build lifecycle. The source files are located in src/site/asciidoc, and the output will be in xhtml5 format with a table of contents on the left. The configuration also includes dependencies for asciidoctorj-pdf, asciidoctorj-diagram, and asciidoctorj-diagram-plantuml. This setup works perfectly on Windows, but Linux throws a wrench in the works.

The Initial Error: Missing `org.jruby.util.IOStreamInput`

When running this configuration under Linux, the initial error encountered was a missing org.jruby.util.IOStreamInput class. This error indicates that a crucial component of JRuby, which Asciidoctor relies on, is not available in the classpath. JRuby is an implementation of Ruby on the Java Virtual Machine (JVM), and Asciidoctor leverages it for its processing capabilities. The absence of this class suggests a dependency issue related to JRuby. This is a common problem when the required JRuby libraries are not correctly included or are not compatible with the environment. Addressing this error is the first step toward resolving the Asciidoctor plugin issue on Linux. The user attempted to resolve this by adding a dependency for jruby-core.

Attempted Solution and Subsequent Error

To resolve the missing org.jruby.util.IOStreamInput error, the user added the following dependency to their pom.xml:

<dependency>
    <groupId>org.jruby</groupId>
    <artifactId>jruby-core</artifactId>
    <version>9.4.14.0</version>
</dependency>

This seemed like a logical step, as it directly addresses the missing JRuby component. However, adding this dependency led to a new error: (LoadError) No such file to load -- asciidoctor. This new error indicates that while the JRuby core components are now available, the Asciidoctor library itself cannot be found. This can occur due to several reasons, such as incorrect paths, version mismatches, or other dependency conflicts. It’s crucial to diagnose this error accurately to apply the correct fix. The error message No such file to load -- asciidoctor specifically points to a problem with loading the Asciidoctor library within the JRuby environment. Now, let's dive into potential solutions for this issue.

Potential Solutions and Workarounds

To tackle the "No such file to load -- asciidoctor" error, we need to consider several approaches. These include verifying dependencies, checking JRuby and Asciidoctor versions, and ensuring proper configuration within the Maven environment. Let's explore each of these solutions in detail.

1. Verify Dependencies and Versions

The first step is to ensure that all necessary dependencies are correctly declared in your pom.xml and that their versions are compatible. In the provided configuration, the user has included dependencies for asciidoctorj-pdf, asciidoctorj-diagram, and asciidoctorj-diagram-plantuml. However, the core asciidoctorj dependency might be missing or have an incompatible version. It's essential to explicitly include asciidoctorj and ensure its version aligns with the asciidoctor-maven-plugin version. A mismatch in versions can lead to loading errors and unexpected behavior. To verify this, add the following dependency to your pom.xml:

<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj</artifactId>
    <version>2.5.11</version>
</dependency>

Make sure the version 2.5.11 is compatible with your asciidoctor-maven-plugin version (3.2.0 in this case). Refer to the Asciidoctor documentation for compatibility matrices. Ensuring correct versions is critical to avoid dependency conflicts. Sometimes, using the latest version might introduce compatibility issues, so it's beneficial to check the release notes for any known problems or incompatibilities.

2. Check JRuby Version Compatibility

The user mentioned that newer 10.x versions of JRuby do not work with Java 17. While JRuby 9.4.14.0 was added as a dependency, it's crucial to verify its compatibility with both Asciidoctor and the asciidoctor-maven-plugin. Incompatibilities can manifest as loading errors or runtime exceptions. It’s advisable to consult the Asciidoctor documentation or community forums for recommended JRuby versions for specific Asciidoctor versions. JRuby compatibility is often a hidden culprit in such issues. A simple version mismatch can lead to significant problems, so double-checking this aspect is essential. If a version conflict is identified, try downgrading or upgrading JRuby to a compatible version.

3. Ensure Proper Plugin Configuration

The asciidoctor-maven-plugin relies on JRuby to execute Asciidoctor. If JRuby is not correctly configured within the plugin, it can lead to loading errors. One way to ensure proper configuration is by explicitly specifying the JRuby version within the plugin configuration. This can be done using the <gemPath> and <jrubyVersion> parameters in the plugin configuration. For example:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>3.2.0</version>
    <executions>
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <sourceDirectory>src/site/asciidoc</sourceDirectory>
                <backend>xhtml5</backend>
                <attributes>
                    <toc>left</toc>
                </attributes>
                <requires>
                    <require>asciidoctor-diagram</require>
                </requires>
                <gemPath>${project.basedir}/.gems</gemPath>
                <jrubyVersion>9.4.14.0</jrubyVersion>
            </configuration>
        </execution>
    </executions>
    ...
</plugin>

Here, <gemPath> specifies the directory where gems (Ruby libraries) are stored, and <jrubyVersion> explicitly sets the JRuby version. Explicit configuration helps the plugin correctly initialize the JRuby environment. By specifying the JRuby version, you ensure that the plugin uses the intended version, reducing the likelihood of version-related issues. The <gemPath> also ensures that gems are loaded from a specific location, which can be crucial in environments where gem installations might be inconsistent.

4. Check for OS-Specific Issues

Since the plugin works on Windows but fails on Linux, there might be OS-specific issues at play. Linux systems often have stricter requirements for library paths and permissions. Ensure that JRuby and Asciidoctor libraries are accessible and that there are no permission issues preventing the plugin from loading them. OS-specific nuances can sometimes be the root cause of such problems. Verify that all necessary libraries are in the classpath and that the user running the Maven build has the required permissions to access them. Sometimes, setting environment variables or modifying the Maven settings file (settings.xml) can help resolve these issues.

5. Use a Gemfile for Dependency Management

Another approach is to use a Gemfile to manage Ruby gem dependencies. A Gemfile is a standard way to manage Ruby dependencies, similar to how pom.xml manages Java dependencies. By including a Gemfile in your project, you can ensure that all required gems, including Asciidoctor, are installed and managed consistently. To use a Gemfile, create a file named Gemfile in your project root directory and add the following content:

source 'https://rubygems.org'

gem 'asciidoctor'

You can also specify versions for the gems if needed:

source 'https://rubygems.org'

gem 'asciidoctor', '2.0.0'

Then, configure the asciidoctor-maven-plugin to use the Gemfile:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>3.2.0</version>
    <executions>
        <execution>
            <id>output-html</id>
            <phase>generate-resources</phase>
            <goals>
                <goal>process-asciidoc</goal>
            </goals>
            <configuration>
                <sourceDirectory>src/site/asciidoc</sourceDirectory>
                <backend>xhtml5</backend>
                <attributes>
                    <toc>left</toc>
                </attributes>
                <requires>
                    <require>asciidoctor-diagram</require>
                </requires>
                <useGemfile>true</useGemfile>
            </configuration>
        </execution>
    </executions>
    ...
</plugin>

This approach ensures that all Ruby dependencies are managed consistently, reducing the risk of version conflicts. Using a Gemfile centralizes dependency management and provides a reproducible build environment. It also simplifies the process of upgrading or downgrading gem versions, as all changes are tracked in the Gemfile.

6. Investigate Classpath Issues

Sometimes, the issue might be related to how the classpath is being constructed in the Linux environment. Ensure that all required JAR files, including JRuby and Asciidoctor dependencies, are present in the classpath. Classpath issues can be tricky to diagnose but are often the cause of loading errors. Verify that no JAR files are missing or corrupted and that the classpath is correctly configured. You can use Maven's dependency tree feature (mvn dependency:tree) to inspect the resolved dependencies and identify any potential conflicts or missing artifacts.

Conclusion

Troubleshooting the Asciidoctor plugin on Linux can be challenging, but by systematically addressing potential issues like dependency conflicts, version mismatches, and configuration errors, you can resolve the problem. Start by verifying your dependencies and their versions, ensuring JRuby compatibility, and properly configuring the plugin. Consider using a Gemfile for dependency management and investigate any OS-specific issues that might be at play. By following these steps, you should be able to get the Asciidoctor plugin working seamlessly on your Linux system.

For more information on Asciidoctor and its ecosystem, visit the Asciidoctor official website. This resource provides comprehensive documentation, guides, and community support to help you effectively use Asciidoctor for your documentation needs.