Upgrading From Older Versions of Asciidoctor

Upgrading to .5.x

If you are on a version 3.x or older, upgrade to 4.x first.

If you are on 4.x you can continue to use the old style, but you need to append .classic to all of your Asciidoctor plugins. If you used org.asciidoctor.jvm.convert, you now need to use org.asciidoctor.jvm.convert.classic

Otherwise in 5.x, the correct way is to use the new model approach, where everything is configured in one place and there is no need to configure any tasks in the DSL.

Notes about upgrading to the new model

  • The base directory is the source directory by default, whereas in the classic plugins it is still the project directory.

  • The base directory is now set prior to conversion. The engine can still adjust the base directory per file, but there is a performance as less files can be converted at one time.

  • The pdfTehemes extension in now called asciidocPdfThemes.

Notes about the classic model in 5.x

  • docExtensions no longer accept closures. Content needs to be passed as a string or loaded from a file. This is due to how Gradle instruments objects in Gradle 8.4+.

  • There is no baseDirFollowSourceFiles. If you really need that behaviour, then you should migrate to the new model.

  • JAVA_EXEC is no longer a valid execution model. It was used as to workaournd classpath leakage in the workers of older Gradle versions.

Upgrading to 4.x

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

projectdir

gradle-projectdir

No

The Gradle project directory which is running the Asciidoctor task.

rootdir

gradle-rootdir

No

The rootproject directory in a multi-project build.

project-name

gradle-project-name

Yes

The name of the current Gradle subproject. (Or the root project in case of a single project).

project-group

gradle-project-group

Yes

The project/artifact group if it is defined.

project-version

revnumber

Yes

The project version if it is defined.

-

gradle-relative-srcdir

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 src/docs/asciidoc/subdir/sample.adoc will set this attribute to .. if sourceDir == src/docs/asciidoc.

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 '5.0.0-alpha.1'
}

repositories {
    ruby.gems()
}

Reveal.js

Follows the same guidelines as for GEMS above.

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.

Extensions

Extensions on the Gradle classpath are no longer detected. You need to declare them explicitly. This includes any extensions created in buildSrc.