Using asciidoctor-bibtex with the Asciidoctor Maven plugin

AsciiDoc and its ruby-based toolchain Asciidoctor have many appealing features for a documentation writer. Among these are the possibility to run Asciidoctor in Maven via a jruby-based plugin and support for BibTeX bibliographies with CSL styles using the asciidoctor-bibtex extension. However, I discovered that combining these two capabilities was a little more complex than anticipated, so I am documenting a solution here and in an accompanying demonstration project. The solution is also applicable to the use of other gem-packaged Asciidoctor extensions with the Asciidoctor Maven plugin.

The Asciidoctor Maven plugin uses jruby to run Asciidoctor on the JVM, and bundles several Asciidoctor ruby extensions. asciidoctor-bibtex is not among these, so has to be provided explicitly. The plugin’s configuration section can specify required ruby gems and a directory in which to look for them:

<plugin>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-maven-plugin</artifactId>
  <version>${asciidoctor.maven.plugin.version}</version>
  <configuration>
    <sourceDirectory>src/docs/asciidoc</sourceDirectory>
    <gemPath>${project.build.directory}/rubygems</gemPath>
    <requires>asciidoctor-bibtex</requires>
  </configuration>
</plugin

There remains the task of fetching the asciidoctor-bibtex gem and its dependencies and placing them in the specified directory as part of the build process. In theory, this is fairly simple: TorqueBox hosts a RubyGems Maven Proxy Repository which provides Maven co-ordinates for every official Ruby gem. However, dependency management turns out to be a problem here: Maven attempts to fetch every possible version of every dependency and transitive dependency, creating a dependency explosion which not only consumes much time, disk space, and bandwidth but actually breaks the build – because a few of those vast numbers of versions are broken. As a workaround, we can use the sets goal of gem-maven-plugin to manually specify all the dependencies and their versions. But how to obtain that information? I did it by installing asciidoctor-bibtex using the standard CRuby gem tool and reading the resulting package information from its local gems directory (~/.gem in my case, since I’d done a user install). The result was the following configuration:

<plugin>
  <groupId>de.saumya.mojo</groupId>
  <artifactId>gem-maven-plugin</artifactId>
  <version>1.1.8</version>
  <executions>
    <execution>
      <id>install-gems-for-asciidoctor</id>
      <goals>
        <goal>sets</goal>
      </goals>
      <configuration>
        <gems>
          <asciidoctor-bibtex>0.7.1</asciidoctor-bibtex>
          <bibtex-ruby>4.4.7</bibtex-ruby>
          <citeproc>1.0.10</citeproc>
          <citeproc-ruby>1.1.12</citeproc-ruby>
          <csl>1.5.1</csl>
          <csl-styles>1.0.1.10</csl-styles>
          <latex-decode>0.3.1</latex-decode>
          <namae>1.0.1</namae>
        </gems>
      </configuration>
    </execution>
</plugin>

This configuration was successful in getting asciidoctor-bibtex working. A minimal working example demonstrating the configuration can be found at https://github.com/pont-us/asciidoctor-bibtex-maven-example.

links

social