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:


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:


This configuration was successful in getting asciidoctor-bibtex working. A minimal working example demonstrating the configuration can be found at