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:

docExtensions	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.
fatalWarnings	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.
jrubyVersion	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.
logLevel	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.
modules	Configuration for version of specific components and converters that can be used. See AsciidoctorJ Modules for which modules are supported.
options	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.
requires	The set of Ruby modules to be included. Use `requires` to append. Use `setRequires` or `requires=['name']` to overwrite. Default: empty.
resolutionStrategy	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.
version	AsciidoctorJ version. If not specified a sane default version will be used.

The following common entities can also be set:

attributes	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.
attributeProviders	Additional sources where attributes can be obtained from. Attribute providers are useful for where changes should not cause a rebuild of the docs.
attributesForLang	Language-specific attributes. Specify additional attributes which will only be added if a source set for the specified language is being processed.
safeMode	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.

build.gradle

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:

build.gradle.kts

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

    attributes(
      mapOf(
        "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 $project.name
gradle-project-version: matches $project.version (if defined). Empty String value if undefined
gradle-project-group: matches $project.group (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:

build.gradle

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:

build.gradle

asciidoctorj {
  modules {
    pdf.version '1.2.3'
  }

  modules.pdf.version '1.2.3'
}

build.gradle.kts

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.

build.gradle

plugins {
    id 'org.asciidoctor.jvm.base' version '4.0.2'
}

build.gradle.kts

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