Task Configuration

All Asciidoctor tasks will have the following methods and properties:

Properties and methods common all AsciidoctorJ tasks

a task extension which allows a task to extend of override global configuration for Asciidoctor tasks. This allows extensive flexibility. Any thing that can be configured in the global asciidoctorj extension can also be configured here.


A shortcut for asciidoctorj.attributes and asciidoctorjs.attributes.


Base directory for asciidoctor document conversion and root document inclusion. The base directory will be the project directory by default, but can be set to any other directory.


The base directory should be the same as the source directory even if the source directory is located within an intermediate working directory.


The base directory should be the same as the directory of each individual source file.


The base directory is always the current project directory.


The base directory is always the root project directory.


Specify additional configurations These configurations will be added to the classpath when the task is executed.


Copy all resources to the output directory


Do not copy any resources to the output directory


Only copy resources if the backend matches the listed backend.


Specifies whether Asciidoctor conversions should be run in-process or out-of-process. Default: JAVA_EXEC. In version 3.x this was called inProcess


Invoke source language support but specifying one or more languages.


Specifies if documents being processed should be logged on console. Type: boolean. Default: false.


A shortcut to asciidoctorj.options.


where generated docs go. Use either outputDir path, setOutputDir path or outputDir=path Type: File, but any object convertible with project.file can be passed. Default: $buildDir/asciidoc.


Specifies whether each backend or other variant of a converting tasks should be run in parallel or sequential. Sequential conversions might have less initialisation overhead, but may suffer from gemPath and extension pollution. Default: true (parallel).


specify which additional files (image etc.) must be copied to output directory using a CopySpec.


Specify which source files should be monitored for change. These are typically files which are included by top-level files as well as doctype files. Default: All files in sourceDir which matches getDefaultSourceDocumentPattern() as well as doctype files.


where the asciidoc sources are. Use either sourceDir path, setSourceDir path or sourceDir=path Type: File, but any object convertible with project.file can be passed. Default: src/docs/asciidoc.


Specify which Asciidoctor source files to include as toplevel documents. It uses an Ant-style PatternSet.


Use an intermediate work directory for sources ances. Some extensions such as ditaa will write content into the source directory. In order to keep the project source directory pristine an intermediate work directory can be used. All sources and resources will be copied there prior the executing Asciidoctor.


Add intermediate artifacts to output directory. If the document conversion process creates intermediate artifacts which needs to be added to the output directory, then the pattern set with a closure or Action. This implies useIntermediateWorkDir. An example of such a case is the use of ditaa.

You will have to configure the properties for each plugin as they are not inherited from one to another. For example you will have to configure languages for both org.asciidoctor.jvm.convert and org.asciidoctor.jvm.pdf plugins if you want multi language pdf and html. Otherwise it wil not work properly. See This issue for more details.

The org.asciidoctor.jvm.convert plugin has a conversion task type of org.asciidoctor.gradle.jvm.AsciidoctorTask which, in addition the aforementioned will also have the following properties and methods which are configured via an outputOptions closure or action:

Properties & methods for configuring generic AsciidoctorTask

the backends to use. Use backends to append. Use setBackends or backends=[] to overwrite Type: Set<String>, but any type can be converted to String can be used. Default: [html5].


specifies whether each backend should use a separate subfolder under outputDir. Default: true

Defining Sources

The plugin will search for sources under sourceDir. Sources may have any of the following extensions in order to be discovered:

  • .adoc (preferred)

  • .asciidoc

  • .ad

  • .asc

To select only certain files, use the sources method. This method takes a closure or an Action as an argument, which in turn configures an org.asciidoctor.gradle.jvm.epub.internal PatternSet.

To specify a custom output folder, use the outputDir method.

asciidoctor {
  sourceDir  file('docs')
  sources {
    include 'toplevel.adoc', 'another.adoc', 'third.adoc'
  outputDir  file('build/docs')
tasks {
  "asciidoctor"(AsciidoctorTask::class) {
    sourceDir = file("docs")
    sources(delegateClosureOf<PatternSet> {
      include("toplevel.adoc", "another.adoc", "third.adoc")
    outputDir = file("build/docs")

Paths defined in this PatternSet are resolved relative to the sourceDir.

Processing Auxiliary Files

Some backends require that additional files be copied across. The most common example are images for HTML backends. For this the resources method is used. It is provided with a closure that configures an org.asciidoctor.gradle.jvm.epub.internal CopySpec

resources {
  from('src/resources/images') {
    include 'images/**/*.png'
    exclude 'images/**/notThisOne.png'

  from( "${buildDir}/downloads" ) {
    include 'deck.js/**'

  into './images'
resources(delegateClosureOf<CopySpec> {
  from("src/resources/images") {

  from("$buildDir/downloads") {


Files will be copied to below ${outputDir}/${backend} (or just ${outputDir} if separateOutputDirs=false)

Unlike sourceDir files can be copied from anywhere in the filesystem.

If resources is never set, the default behaviour is as if the following was called

resources {
  from(sourceDir) {
    include 'images/**'

In case of languages the default behaviour is

resources {
  from(new File(sourceDir,"${langName}")) {
    include 'images/**'

If you do not want this behaviour, then it can be turned off by doing


If you are using multiple languages and you have identical resource patterns for each language within sourceDir/${lang} you need to explicitly declare those on a per-language basis:

resources 'en', {
  from("${sourceDir}/en") {
    include 'images/**'

resources 'es', {
  from("${sourceDir}/es") {
    include 'images/**'

Include directives and base directory

These plugins do not change the way include:: directive works, but it is important to note how setting baseDir will affect top level includes. It is recommended that you always use {includedir} as a prefix for the file path. This attribute is always set to the correct top-level folder where the sources will be located.

However, it is not practical for everyone to use {includedir} and as from 2.2.0 it is possible to add a strategy for controlling the base directory:

asciidoctor {
    baseDirIsRootProjectDir() (1)
    baseDirIsProjectDir() (2)
    baseDirFollowsSourceDir() (3)
    baseDirFollowsSourceFile() (4)
1 The base directory is the root project directory.
2 The base directory is the current subproject directory.
3 The base directory will always the the same as the source directory. If an intermediate working directory is being used, the base directory will automatically point to that.
4 The base directory will be the same as the directory of each individual source file.

Docinfo processing

When using the docinfo attribute with html and docbook backends, it is recommended that baseDirFollowsSourceDir() is always set. This will ensure that the docinfo files are picked up correctly from the same directory that is the source directory.

Source language support

Some scenarios work on a source set of documents in a primary language and then translations of those sources into other languages. The Gradle plugin simplifies this scenario by allowing a structure such as

│   └── src
│       ├── asciidoc
│       │   └── en
│       │       └── index.adoc
│       │   └── es
│       │       └── index.adoc

This can be enabled in the DSL by doing

asciidoctor {
    languages 'en', 'es'

Gradle will then process both the en and the es source set and output to the output directory using the same languages names. Intermediate working directories and multiple backends are also covered. In this case the lang attribute will be injected with the specific language as the value.

It is also possible to specify additional attributes that will only be added when a specific language is processed

asciidoctorj { (1)
    attributesForLang 'en', langName : 'English'
    attributesForLang 'ca', langName : 'Catala'

asciidoctorjs { (2)
    attributesForLang 'en', langName : 'English'
    attributesForLang 'ca', langName : 'Catala'
1 Configuration when using AsciidoctorJ
2 Configuration when using Asciidoctor.js

Choosing a Process Mode for AsciidoctorJ

All AsciidoctorJ-based tasks can control how Asciidoctor conversions are being run via the inProcess property. This is early days, and a choice for your build will depend very much on your context, but the following has already become clear:

  • IN_PROCESS and OUT_OF_PROCESS should theoretically run faster, especially if you continuously rebuild the same documentation. Gradle workers are the underlying implementation for these two options

  • The safe option is always JAVA_EXEC. For lower memory consumption this is by far the safer option. (It is also the only way we can get the Windows-based tests for this plugin to complete on Appveyor & Travis CI). It you run a lot of builds the penalty start-up time might become an issue for you.

In certain cases the plugin will overrule your choice as it has some built-in rules for special cases. In such cases it will log a warning that it has done that.