Asciidoctor Gradle Plugin | Asciidoctor

The plugin adds a new task named asciidoctor. You can configure this task using the following configuration properties and methods.



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


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



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 by using an Ant-style PatternSet.


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


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.


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


one or more gem installation directories (separated by the system path separator). Use gemPath to append. Use setGemPath or gemPath=’path to overwrite. Use asGemPath to obtain a path string, separated by platform-specific separator. For backwards-compatibility, setGemPath and gePath=’string’ will accept a path string containing the platform-specific separator. Type: FileCollection, but any collection of objects convertible with project.files can be passed Default: empty


a set of Ruby modules to be included. Use requires to append. Use setRequires or requires=’name’ to overwrite. Type: Set. Default: empty.


a Map specifying different options that can be sent to Asciidoctor. Use options to append, Use setOptions or options= to overwrite.


a Map specifying various document attributes that can be sent to Asciidoctor Use attributes to append, Use setAttributes or attributes= to overwrite.

To see examples of many of these configuration options used in practice, refer to the Asciidoctor Gradle Examples project.

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 as an argument, which in turn configures an 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’) }

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

For the Gradle Kotlin DSL a workaround is needed:


tasks { “asciidoctor”(AsciidoctorTask::class) { sourceDir = file(“docs”) sources(delegateClosureOf { include(“toplevel.adoc”, “another.adoc”, “third.adoc”) }) outputDir = file(“build/docs”) } }

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 internal CopySpec


resources { from(‘src/resources/images’) { include ‘images/**/*.png’ exclude ‘images/**/notThisOne.png’ } from( “$/downloads” ) { include ‘deck.js/**’ } into ‘./images’ }

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

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

For the Gradle Kotlin DSL, the example above looks like this:


resources(delegateClosureOf { from(“src/resources/images”) { include(“images/**/*.png”) exclude(“images/**/notThisOne.png”) } from(“$buildDir/downloads”) { include(“deck.js/**”) } into(“./images”) })

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


resources { from(sourceDir) { include ‘images/**’ } }

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

Options & Attributes

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

  • header_footer – boolean

  • template_dirs – List

  • 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.


asciidoctor { (1) outputDir “$/docs” options doctype: ‘book’, ruby: ‘erubis’ attributes ‘source-highlighter’: ‘coderay’, toc : ”, idprefix : ”, idseparator : ‘-‘ }

Or in the Gradle Kotlin DSL:


tasks { “asciidoctor”(AsciidoctorTask::class) { (1) outputDir = file(“$buildDir/docs”) options(mapOf(“doctype” to “book”, “ruby” to “erubis”)) attributes( mapOf( “source-highlighter” to “coderay”, “toc” to “”, “idprefix to “”, “idseparator” to “-” ) ) } }

1 append below the line: apply plugin: ‘org.asciidoctor.convert’

The following attributes are automatically set by the asciidoctor task:

  • project-name : matches $

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

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

These attributes may be overridden by explicit user input.

You may need to include extra content into the head of the exported document. For example, you might want to include jQuery inside the element of the HTML export. To do so, first create a docinfo file src/docs/asciidoc/docinfo.html containing the content to include, in this case the

Then, add the docinfo1 attribute to the attributes list in the previous example:

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.


Leave a Reply

Your email address will not be published. Required fields are marked *