One of the great features of Asciidoctor is the support for extensions. If we want to have some special feature we want to use, but is not supported by Asciidoctor, we can add our own extension. On the Java platform we can write those extensions in for example Java and Groovy. When we use Gradle as the build tool with the Asciidoctor plugin we can write the code for the extension in our Gradle build file with the Groovy extension DSL.

Suppose we want to write a new inline macro that will transform the following markup issue:PRJ-100[] into a link that points to the web page for issue PRJ-100. First we create our Asciidoctor source document:

= Sample

This is an issue issue:PRJ-100[].

Now we write the following Gradle build file. First we include the Gradle Asciidoctor plugin. Then we can use the extensions configuration method to add our code for the inline macro. If we would write another type of extension we could still use the same place to add it, but then we don't use inlinemacro.

buildscript {
    repositories {
        jcenter()
    }

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

// Apply the Asciidoctor Gradle plugin.
apply plugin: 'org.asciidoctor.convert'


asciidoctor {

    // Here we can add the code for extensions we write.
    extensions {

        // Implementation for inline macro to replace
        // issue:[] with a link to the issue.
        inlinemacro (name: "issue") {
            parent, target, attributes ->

            options = [
                "type": ":link",
                "target": "http://issue-server/browse/${target}".toString()
            ]

            // Create the link to the issue.
            createInline(parent, "anchor", target, attributes, options).render()
        }

    }
}

Let's transform our sample Asciidoctor markup to HTML. We see the following result:

The link that is generated is http://issue-server/browse/PRJ-100.

Written with Gradle 2.3 and Asciidoctor 1.5.2.

Original article

shadow-left