Extensions API

One of the major improvements to Asciidoctor recently is the extensions API. AsciidoctorJ brings this extension API to the JVM environment allowing us to write extensions in Java instead of Ruby.

If you are migrating existing extensions to a newer version, please see the guides:

Writing an extension is as simple as creating a Java class and sub-classing from one of the extension points. However, to explore the full potential it’s recommended to:

  1. Have a brief understanding of the AsciidoctorJ conversion process and internal representation of the document. In short, extensions allow you to tap into the conversion process to make modifications to enhance the generated content.

  2. Write an extension class. This is as simple as creating a subclass from one of the extension points listed below.

  3. Register your class to make AsciidoctorJ converter aware of it. There several options depending on the use case.

Asciidoctor provides eight types of extension points. Each extension point has an abstract class in Java that maps to the extension API in Ruby.

AsciidoctorJ extension APIs
Name Class Description

Include Processor


Intercepts include::[] lines



Allows you to modify the asciidoc text before parsing

Block Macro Processor


Processes block macros like bibliography::[]

Block Processor


Processes an arbitrary block based on it’s style such as

Do not enter



Modify the AST after parsing.

Inline Macro Processor


Processes inline macros like btn:[].



Modifies the backend-specific output document.

Docinfo Processor


Insert content into the header element or the end of the body element (html), or the info element or at the end of the document (docbook).