AsciidoctorJ Base Plugin

This plugin is automatically applied by all AsciidoctorJ-based plugins.

Adds an extension for configuring which version of AsciidoctorJ and various other AsciidoctorJ backends.

This is very much similar to the one used in older versions of the Asciidoctor Gradle plugin, but now it also offers the ability to add the same functionality to a task thus allowing a task to override the default versions that has been set.

asciidoctorj {
  version = '1.5.6' (1)
  groovyDslVersion = '1.0.0.Alpha2' (2)

  options doctype: 'book', ruby: 'erubis' (3)

  attributes toclevel : 2 (4)
1 Set the default version of AsciidoctorJ for all Asciidoctor tasks in a project.
2 Set the default version of the Groovy extensions DSL for all Asciidoctor tasks in a project.
3 Add options for all Asciidoctor tasks
4 Add attributes for all Asciidoctor tasks

You can also override or extend select settings within a task using the same extension i.e.

asciidoctor {
  asciidoctorj {
      setOptions = [ doctype: 'article' ] (1)

      attributes toc : left (2)
1 Override any global options
2 Use these attributes in addition to the globally specified ones.

The AsciidoctorJ-specific entities that can be set are:


Groovy DSL and project-based extensions. Use docExtensions to add one or more extensions. Use setDocExtensions to replace the current set of extensions with a new set. Extensions can be any kind of object that is serialisable, although in most cases they will be strings or files. If extensions are detached dependencies, they will not be serialised, but rather will be placed on the classpath in order that AsciidoctorJ can pick them up automatically. See <asciidoctorj-extensions>> for more details.


Patterns for AsciidoctorJ log messages that should be treated as fatal errors. The list is empty be default. Use setFatalWarnings to clear any existing patterns or to decouple a task’s configuration from the global configuration. Use fatalWarnings to add more patterns. Pass missingIncludes() to add the common use-case of missing include files.


Minimum version of JRuby to be used. The exact version that will be used could be higher due to AsciidoctorJ having a transitive dependency that is newer.


The log level at which AsciidoctorJ will log. This is specified as a Gradle logging level. The plugin will translate it to the appropriate AsciidoctorJ logging level. Default is whatever project.logger.level is at the time of execution.


Configuration for version of specific components and converters that can be used. See AsciidoctorJ Modules for which modules are supported.


AsciidoctorJ options. Use options to append and setOptions to replace any current options with a new set. Options are evaluated as late as possible. See Setting Options for more details.


The set of Ruby modules to be included. Use requires to append. Use setRequires or requires=['name'] to overwrite. Default: empty.


Strategies for resolving Asciidoctorj-related dependencies. AsciidoctorJ dependencies are held in a detached configuration. If for some special reason, you need to modify the way the dependency set is resolved, you can modify the behaviour by adding one or more strategies.


AsciidoctorJ version. If not specified a sane default version will be used.

The following common entities can also be set:


Asciidoctor attributes. Use attributes to append and setAttributes to replace any current attributes with a new set. Attribute values are lazy-evaluated to strings. See Setting Attributes for more detail.


Additional sources where attributes can be obtained from. Attribute providers are useful for where changes should not cause a rebuild of the docs.


Language-specific attributes. Specify additional attributes which will only be added if a source set for the specified language is being processed.


Asciidoctor safe mode. Set the Safe mode as either UNSAFE, SAFE, SERVER, SECURE. Can be a number (0, 1, 10, 20), a string, or the entity name

Options & Attributes

The following options may be set using the extension’s options property

  • header_footer - boolean

  • template_dirs - List<String>

  • template_engine - String

  • doctype - String

Any key/values set on attributes is sent as is to Asciidoctor. You may use this Map to specify a stylesheet for example. The following snippet shows a sample configuration defining attributes.

asciidoctorj { (1)
    options doctype: 'book', ruby: 'erubis'

    attributes 'source-highlighter': 'coderay',
                toc                 : '',
                idprefix            : '',
                idseparator         : '-'
1 This can be globally on the project extension or locally on the task’s extension.

Or in the Gradle Kotlin DSL:

tasks {
  "asciidoctor"(AsciidoctorTask::class) { (1)
    options(mapOf("doctype" to "book", "ruby" to "erubis"))

        "source-highlighter" to "coderay",
        "toc"                to "",
        "idprefix"           to "",
        "idseparator"        to "-"
1 This is an example of setting it on the task extension in Kotlin.

The following attributes are automatically set by the asciidoctorj extension:

  • gradle-project-name : matches $

  • gradle-project-version: matches $project.version (if defined). Empty String value if undefined

  • gradle-project-group: matches $ (if defined). Empty String value if undefined

These attributes may be overridden by explicit user input.

Refer to the Asciidoctor Documentation to learn more about these options and attributes.

Attribute values defined on the build file will win over values defined on the documents themselves. You can change this behavior by appending an @ at the end of the value when defined in the build file. Please refer to Attribute assignment precedence for more information.

Versions of modules

The modules block currently supports five elements:

asciidoctorj {
  modules {
    pdf { (1)
      version '1.2.3'
    epub { (2)
      version '1.2.3'
    diagram { (3)
      version '1.2.3'
    groovyDsl { (4)
      version '1.2.3'
    leanpub { (5)
      version '1.2.3'
1 AsciidoctorJ PDF version. If not specified asciidoctorj-pdf will not be on the classpath. If you plan to use the PDF backend and not using the PDF plugin, then you need to set a version here.
2 AsciidoctorJ EPUB3 version. If not specified asciidoctorj-epub will not be on the classpath. If you plan to use the EPUB backend and not using the EPUB plugin, then you need to set a version here.
3 See Using AsciidoctorJ Diagram.
4 Version of Groovy Extensions DSL. If not specified and no extensions are specified, Groovy DSL will not be used. However, if any extensions are added without setting an explicit version and default version will be used.
5 Asciidoctor Leanpub Converter version. If not specified asciidoctorj-leanpub will not be on the classpath. If you plan to use the Leanpub backend and not using the Leanpub plugin, then you need to set a version here.

When using the Kotlin DSL the same settings can be achieved use something similar: getModules().getPdf().version("1.2.3"). In a similar fashion shortcuts can be achieved in the Groovy DSL:

asciidoctorj {
  modules {
    pdf.version '1.2.3'

  modules.pdf.version '1.2.3'
asciidoctorj {
  getModules().getPdf().version("1.2.3") (1)
  getModules().getPdf().use() (2)
1 Set the AsciidoctorJ PDF version to 1.2.3.
2 Use the default version of AsciidoctorJ PDF.

Applying the AsciidoctorJ Base plugin on its own

If none of the default conventions work for you, the base plugin can be applied on its own.

plugins {
    id 'org.asciidoctor.jvm.base' version '4.0.2'
plugins {
    id("org.asciidoctor.jvm.base") version "4.0.2"