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 us 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 sub-class 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

org.asciidoctor.extension.IncludeProcessor

Intercepts include::[] lines

Preprocessor

org.asciidoctor.extension.Preprocessor

Allows you to modify the asciidoc text before parsing

Block Macro Processor

org.asciidoctor.extension.BlockMacroProcessor

Processes block macros like bibliography::[]

Block Processor

org.asciidoctor.extension.BlockProcessor

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

[prohibited]
--
Do not enter
--

Treeprocessor

org.asciidoctor.extension.Treeprocessor

Modify the AST after parsing.

Inline Macro Processor

org.asciidoctor.extension.InlineMacroProcessor

Processes inline macros like btn:[].

Postprocessor

org.asciidoctor.extension.Postprocessor

Modifies the backend-specific output document.

Docinfo Processor

org.asciidoctor.extension.DocinfoProcessor

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