Writing an AsciidoctorJ Extension

1. Intro

One of the features of AsciiDoctor I really like is the ability to write custom extensions. In this post we will be using the Java version of the AsciiDoctor processor called AsciiDoctorJ. Instead of Using Java I will be using Kotlin, cause why not. There are different types of Extensions, see the list here. In this post we will write an extension using the BlockMacro Processor extension. This extension will create an "interactive" SVG which is just a button that you can click in html and just a flat image in PDF. Let’s Begin!

2. Project Setup

We will be using Apache Maven for our build process. So let’s create a maven project using the maven cli.

Copy the command below and run it replacing groupID with your value .This assumes mvn is in the path

mvn archetype:generate -DgroupId=gy.roach.extension -DartifactId=hello-svg -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

Open Project in IDE, preferred IDE here is Jetbrains' Intellij Idea.
Modify the pom.xml file by adding the AsciidoctorJ dependency.

dependency

<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj</artifactId>
    <version>2.5.2</version>
    <scope>provided</scope> (1)
</dependency>

1	using provided as the scope ensuring this extension does not override your setup with AsciiDoctorJ.

Now we are ready to start creating the extension. first we will create an extension registry which will automatically register the block processor.

3. Create Extension Registry

Use an AsciidoctorJ extension registry to automatically load your extensions when the asciidoctor processor starts up.
- Create directory META-INF/services under the src/main/resources directory.
- create a file named org.asciidoctor.jruby.extension.spi.ExtensionRegistry inside the services' directory.
- Let’s add the registry class here. gy.roach.extension.HelloSVGRegistry
- Create this class HelloSVGRegistry inside the package above.

Unix

cd src/main/resource
mkdir META-INF/services
cd META-INF/services
touch org.asciidoctor.jruby.extension.spi.ExtensionRegistry
vim org.asciidoctor.jruby.extension.spi.ExtensionRegistry
#type : edit mode
#paste gy.roach.extension.HelloSVGRegistry into this vim editor
#type escape to end edit mode
:wq!

Windows

cd src/main/resource
mkdir META-INF/services
cd META-INF/services
notepad org.asciidoctor.jruby.extension.spi.ExtensionRegistry
#paste gy.roach.extension.HelloSVGRegistry into this vim editor
#save and exit

Once finished we will now move onto the actual Extension Registry code.

3.1. Using Kotlin for the source code

Create class gy.roach.extension.HelloSVGRegistry kt or java depending on your choice.

Kotlin

package gy.roach.extension

import org.asciidoctor.Asciidoctor
import org.asciidoctor.jruby.extension.spi.ExtensionRegistry

class HelloSVGRegistry : ExtensionRegistry {
    override fun register(asciidoctor: Asciidoctor) {
        val registry = asciidoctor.javaExtensionRegistry()
        registry.block(HelloSVGBlockProcessor::class.java)
    }
}

Java

package gy.roach.extension;

import org.asciidoctor.Asciidoctor;
import org.asciidoctor.jruby.extension.spi.ExtensionRegistry;

class HelloSVGRegistry extends ExtensionRegistry {
    @Override void register(Asciidoctor asciidoctor ) {
        JavaExtensionRegistry registry = asciidoctor.javaExtensionRegistry();
        registry.block(HelloSVGBlockProcessor.class);
    }
}

In the registry.block(..) we identified the class that will be our extension. So let’s go ahead and create it.

In this example, we are going to use the AsciiDoctorJ BlockProcessor to generate an SVG button that will link to amazon.com. Fairly simple diagram to render an image that can be interactive.

3.2. Source Code to HelloSVGBlockProcessor.kt

Kotlin

package gy.roach.extension

import org.asciidoctor.ast.ContentModel
import org.asciidoctor.ast.StructuralNode
import org.asciidoctor.extension.BlockProcessor
import org.asciidoctor.extension.Contexts
import org.asciidoctor.extension.Name
import org.asciidoctor.extension.Reader
import java.util.*

@Name("hello")
@Contexts(Contexts.LISTING)
@ContentModel(ContentModel.COMPOUND)
class HelloSVGBlockProcessor : BlockProcessor() {
    override fun process(parent: StructuralNode, reader: Reader, attributes: MutableMap<String, Any>): Any {
        val filename = attributes.getOrDefault("2", "${System.currentTimeMillis()}_unk") as String
        val content = reader.read()
        val sb = fromStrToSvg(content)
        val svg = File("${reader.dir}/images/${filename}.svg")
        svg.writeBytes(sb.toByteArray())
        val blockAttrs = mutableMapOf<String, Any>(
            "role" to "roach.gy.hello",
            "target" to "images/${filename}.svg",
            "alt" to "IMG not available",
            "title" to "Figure. $filename",
            "interactive-option" to "",
            "format" to "svg"

        )
        return createBlock(parent, "image", ArrayList(), blockAttrs, HashMap())
    }

    private fun fromStrToSvg(input: String) : String {
        val parsed = input.split("|")
        return """
          <?xml version="1.0" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     viewBox="0 0 100 100">
    <defs>
        <linearGradient id="linear-gradient-5" gradientUnits="userSpaceOnUse" x1="781.482" y1="79.988" x2="781.482"
                        y2="49.983">
            <stop offset="0" stop-color="#cb43f6" stop-opacity="1"/>
            <stop offset="1" stop-color="#ec4cbd" stop-opacity="1"/>
        </linearGradient>
    </defs>
    <style>
        circle.card {
            pointer-events: bounding-box;
            opacity: 1;
        }

        circle.card:hover {
            opacity: 0.6;
        }
        .fancy {
            font-size: 12px;
            font-weight: bold;
            fill: #fffef7;
            font-family: "Noto Sans",sans-serif;
        }
    </style>
        <a xlink:href="${parsed[1]}" target="_blank">
        <g>
            <circle cx="50" cy="50" fill="url(#linear-gradient-5)" r="45" class="card"/>
            <text x="50" y="50" text-anchor="middle" class="fancy">${parsed[0]}</text>
        </g>
        </a>
</svg>
        """.trimIndent()
    }
}

Java

package gy.roach.extension;

import org.asciidoctor.ast.ContentModel;
import org.asciidoctor.ast.StructuralNode;
import org.asciidoctor.extension.BlockProcessor;
import org.asciidoctor.extension.Contexts;
import org.asciidoctor.extension.Name;
import org.asciidoctor.extension.Reader;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.Map;

@Name("hello")
@Contexts(Contexts.LISTING)
@ContentModel(ContentModel.COMPOUND)
class HelloSVGBlockProcessor extends BlockProcessor {

    @Override
    public Object process(StructuralNode parent, Reader reader , Map<String, Object> attributes) {

        var filename = attributes.getOrDefault("2", "${System.currentTimeMillis()}_unk");
        var content = reader.read();
        var sb = fromStrToSvg(content);
        var svg = new File("${reader.dir}/images/${filename}.svg");
        try {
            new FileOutputStream(svg).write(sb.getBytes(StandardCharsets.UTF_8));
        } catch (IOException e) {
            e.printStackTrace();
        }
        //svg.writeBytes(imgSrc.toByteArray());
        var blockAttrs = new HashMap<String, Object>();
        blockAttrs.put("role", "roach.gy.hello");
        blockAttrs.put("target", "images/${filename}.svg");
        blockAttrs.put("alt", "IMG not available");
        blockAttrs.put("title", "Figure. $filename");
        blockAttrs.put("interactive-option", "");
        blockAttrs.put("format", "svg");

        return createBlock(parent, "image", new ArrayList<>(), blockAttrs, new HashMap<>());
    }

    private String fromStrToSvg(String input)  {
        var parsed = input.split("\\|");
        var str =  """
<?xml version="1.0" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     viewBox="0 0 100 100">
    <defs>
        <linearGradient id="linear-gradient-5" gradientUnits="userSpaceOnUse" x1="781.482" y1="79.988" x2="781.482"
                        y2="49.983">
            <stop offset="0" stop-color="#cb43f6" stop-opacity="1"/>
            <stop offset="1" stop-color="#ec4cbd" stop-opacity="1"/>
        </linearGradient>
    </defs>
    <style>
        circle.card {
            pointer-events: bounding-box;
            opacity: 1;
        }

        circle.card:hover {
            opacity: 0.6;
        }
        .fancy {
            font-size: 12px;
            font-weight: bold;
            fill: #fffef7;
            font-family: "Noto Sans",sans-serif;
        }
    </style>
        <a xlink:href="%s" target="_blank">
        <g>
            <circle cx="50" cy="50" fill="url(#linear-gradient-5)" r="45" class="card"/>
            <text x="50" y="50" text-anchor="middle" class="fancy">%s</text>
        </g>
        </a>
</svg>
        """;
        return String.format(str,parsed[1], parsed[0]);
    }


}

What’s happening in the code?

The Filename is generated or if passed in the block definition as parameter 2 then use it.
content is read from the body of the block macro
parse the body, extracting the label and the url using the pipe(|) separator character.
use the multiline String feature in Kotlin or Java 17+ to pass in the two variables, label and url.
Take the content of the string and write it to the file.
create the AsciiDoctor attributes map for the image.
finally create an asciidoctor block(block here contains an image) to be added to the document.
- Lots of improvements can be made here. Checking if the document contains an imagesdir property then use that directory instead of always expecting images/filename.svg

If you run the maven command to compile and all looks good, we can move on to the packaging step.

4. Package

Now that we have the two source files we can run the maven instal or deploy command to bundle our extension and publish it locally on your machine or deploy to maven central.
Once Published, you can now add the dependency to your maven or gradle project.

To test it out, we will create a unit test that will run the asciidoctor converter and generate the document.

Kotlin

import org.asciidoctor.Asciidoctor
import org.asciidoctor.Attributes
import org.asciidoctor.Options
import org.asciidoctor.SafeMode
import org.asciidoctor.jruby.AsciiDocDirectoryWalker

fun main() {
    val asciidoctor = Asciidoctor.Factory.create()
    val walker = AsciiDocDirectoryWalker("src/main/asciidoc")
   val files = walker.scan()
   val attrs = Attributes.builder()
       .sourceHighlighter("highlightjs")
       .allowUriRead(true)
       .dataUri(true)
       .copyCss(true)
       .noFooter(true)
       .build()
   val options = Options.builder()
       .backend("html")
       .attributes(attrs)
       .safe(SafeMode.SAFE)
       .build()
    asciidoctor.convertDirectory(files, options)
}

Create a file hello.adoc^[1] and drop it into the src/main/asciidoc directory
hello.adoc
```
    [hello]
    ----
    Amazon|https://www.amazon.com
    ----
```
Code will Start at root directory
Grab all files
Set up the AsciiDoctor Converter
finally, convert directory

Now part of your document will contain an imagem like below. This adoc file is actually using that syntax to generate this image blow.

4.1. Output

5. Acknowledgement

Dan Allen (mojavelinux) - Great community leader for the open source asciidoctor project.
Alexander Schwartz - For the wonderful IntelliJ Idea plug-in
Robert Panzer - For keeping the AsciiDoctorJ branch in lock step with the asciidoctor project.,
Dear Friends:
- Ian.C.R, Mike.O.D, Manu.K.
Many others contributing to this wonderful open source project.

6. Links

1. This assumes a maven project structure was created and all asciidoc files are under src/main/asciidoc