Upgrading From Older Versions of Asciidoctor
| If you are still on a 1.5/1.6 version of the plugin, upgrade to the latest 2.x version first. |
If you are on 2.x version, upgrade to the latest 2.x first and ensure that you have corrected all of the deprecation warnings.
If you have AsciidoctorJ binary extensions you’ll need to recompile them against AsciidoctorJ v2.0+ in order to use them with the v.3x version of the plugins.
Old name |
New name |
Substituable |
Usage |
|
|
No |
The Gradle project directory which is running the Asciidoctor task. |
|
|
No |
The rootproject directory in a multi-project build. |
|
|
Yes |
The name of the current Gradle subproject. (Or the root project in case of a single project). |
|
|
Yes |
The project/artifact group if it is defined. |
|
|
Yes |
The project version if it is defined. |
- |
|
No |
The relative path from the parent of the current document that is being processed to the source document root. It is calcluated as moving from the current document towards the root. For instance |
Substitutable attributes means that the build script author can change those attributes by setting them explicitly.
Asciidoctor compatibility tasks
The Asciidoctor compatibility task has been removed. You need to use the Asciidoctor task from org.asciidoctor.jvm.convert instead.
GEMs
If you used external GEMs via the JRuby Gradle plugin, you should switch over to using org.asciidoctor.jvm.gems instead. You should also use the asciidoctorGems configuration rather than the gems configuration. Tasks should not depend on JRubyPrepare, but on AsciidoctorGemsPrepare instead.
If you have the following in your build
plugins {
id 'org.asciidoctor.jvm.gems' version '2.4.1'
id 'com.github.jruby-gradle.base' version '1.7.0'
}
repositories {
rubygems('https://rubygems.org')
}then change it to
plugins {
id 'org.asciidoctor.jvm.gems' version '4.0.2'
}
repositories {
ruby.gems()
}Configurations
The asciidoctor configuration is no longer available. If you used that before to make artifacts available on the classpath you should use the configurations method on the task to add them. If you used it to manipulate versions of AsciidoctorJ and JRuby then you should rather use the explicit versions settings on asciidoctorj.
Multiple Asciidoctor tasks
If you have more than one Asciidoctor task, decide which options, attributes and requires should go in the asciidoctorj global project extension block and which should be customised within the tasks asciidoctor extension block.
Importantly, you probably did import org.asciidoctor.gradle.AsciidoctorTask. You will need to change that to import org.asciidoctor.gradle.jvm.AsciidoctorTask.