Tips & Tricks

Issues with plugins that modify project.version

Plugins such as Nebula Release and Reckon modify project.version with a non-serialisable object. This breaks the build.

The safest workaround is to set the revnumber attribute to a delayed evaluation of project.version in your build:

asciidoctorj {
    attributes revnumber : { project.version.toString() }
}

Pre-process and post-process

To make your own custom actions before or after asciidoctor processing, use doFirst and doLast. Check out chapters 14 and 17 in the Gradle docs to learn about the various actions you can perform.

build.gradle

asciidoctor.doFirst {
  // pre-process
}
asciidoctor.doLast {
  // post-process
}

As an example, here’s how to copy the generated index.html file to the root of the project. This is useful in Windows systems where asciidoctor can’t output directly to the root.

build.gradle

asciidoctor.doLast {
    copy {
        from 'build/docs/html5'
        into "$projectDir"
        include 'index.html'
    }
}

Using Pygments source highlighter

You need to have Python 2.x installed on a system or in a container for Pygments to work.

plugins {
  id 'org.asciidoctor.jvm.pdf' version '4.0.2'
  id 'org.asciidoctor.jvm.gems' version '4.0.2'
}

repositories {
    jcenter()
    ruby.gems()
}

dependencies {
  asciidoctorGems 'rubygems:pygments:1.2.1'
}

asciidoctorPdf {
  dependsOn asciidoctorGemsPrepare
  sourceDir 'docs'

  asciidoctorj {
    requires 'pygments'
    attributes 'source-highlighter' : 'pygments'
  }
}