Asciidoctor Gradle Plugin

The asciidoctor-gradle-plugin is the official means of using Asciidoctor to render all your AsciiDoc documentation using Gradle.

This is a port of the asciidoctor-maven-plugin project by @LightGuard. Relies on asciidoctor-java-integration by @lordofthejars.

Installation

Use the following snippet inside a Gradle build file:

build.gradle

buildscript {
    repositories {
        maven {
            name 'Bintray Asciidoctor repo'
            url  'http://dl.bintray.com/content/aalmiray/asciidoctor'
        }
        jcenter()
    }

    dependencies {
        classpath 'org.asciidoctor:asciidoctor-gradle-plugin:0.7.0'
    }
}

apply plugin: 'asciidoctor'

Usage

The plugin adds a new task named asciidoctor. This task exposes 6 properties as part of its configuration

sourceDir	where the asciidoc sources are. Type: File. Default: `src/asciidoc`.
sourceDocumentName	an override to process a single source file. Type: File. Defaults to all files in `${sourceDir}`
outputDir	where generated docs go. Type: File. Default: `$buildDir/asciidoc`.
backend	the backend to use. Type: String. Default: `html5`.
options	a Map specifying different options that can be sent to Asciidoctor.
logDocuments	a boolean specifying if documents being processed should be logged on console. Type: boolean. Default: `false`

Sources may have any of the following extensions in order to be discovered

.asciidoc
.adoc
.asc
.ad

Configuration

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

header_footer - boolean
template_dir - String
template_engine - String
compact - boolean
doctype - String
attributes - Map

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

build.gradle

// append below the line: apply plugin: 'asciidoctor'

asciidoctor {
    outputDir = new File("$buildDir/docs")
    options = [
        eruby: 'erubis',
        attributes: [
            'source-highlighter': 'coderay',
            toc: '',
            idprefix: '',
            idseparator: '-'
        ]
    ]
}

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

src/asciidoc/docinfo.html

<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.0.3/jquery.js"></script>

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

build.gradle

attributes: [
    // ...
    docinfo1: '',
    // ...
]

The value of attributes my be specified as a Map, List, Array or String, for example the following Map definition

build.gradle

options = [
    attributes: [
        toc: 'right',
        'source-highlighter': 'coderay',
        'toc-title': 'Table of Contents'
    ]
]

may be rewritten in List/Array form as follows

build.gradle

options = [
    attributes: [
        'toc=right',
        'source-highlighter=coderay',
        'toc-title=Table of Contents'
    ]
]

or in String form like so

build.gradle

options = [
    attributes: 'toc=right source-highlighter=coderay toc-title=Table\\ of\\ Contents'
]

Notice how spaces are escaped in the last key/value pair.

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

rwinch / asciidoctor-gradle-plugin Goto Github PK