The asciidoctor-java-integration is the official means of using Asciidoctor to render all your AsciiDoc documentation using Java instead of Ruby.

Installation

Since asciidoctor-java-integration is a standard jar file, the only thing you should do is add library into classpath.

Dependency declaration in Maven
Dependency declaration in Gradle
  1. As this library tracks the version of asciidoctor, you can use whichever version of asciidoctor you prefer.

Usage

The core interface of asciidoctor-java-integration is Asciidoctor interface. It provides two methods for rendering asciidoc content, render and renderFile. Both of them returns a string with rendered content.

Table 1. Method description

Name

Description

render

Parse the AsciiDoc content into a Document and render it to the specified backend format.

renderFile

Parse the content of AsciiDoc file into a Document and render it to the specified backend format.

Also a factory method is provided to create an instance of Asciidoctor interface.

Creation of Asciidoctor interface

And then we can call render methods depending on our requirements.

Rendering a String

But also you can render the content of a file.

Rendering a File

Or a list of Asciidoc files:

Rendering a list of files.

If the rendered content is not written into files, renderDirectory will return an array listing all the documents rendered.

Another method provided by Asciidoctor interface is renderDirectory. This method renders all AsciiDoc files (.asc,+ .asciidoc+,+ .ad+ or .adoc), that are present inside provided folder or any of its subfolder.

In case rendered content is not written in files, this method returns an array with all documents rendered.

Rendering all files of directory

Another way to render AsciiDoc content is by calling render method but providing a Reader and Writer. Reader interface is used as source, and rendered content is written through Writer interface.

Rendering content to a Writer

Options

Asciidoctor supports different kind of options, like in_place which renders the output inside a file, template_dir used to provide a directory of Tilt-compatible templates to be used instead of the default built-in templates, or for example attributes option where we can set key-value pairs of attributes that will be used within asciidoc document.

The second parameter of render methods are a java.util.Map where all these options can be set.

Example of using in_place Option and backend Attribute

See that in previous example we have created a Map, where we have put the options and attributes (creating a Map too) required to render input as docbook and generate an output file.

Another way for setting options is by using org.asciidoctor.Options class. Options is a simple Java class which contains methods for setting required options. Note that related with org.asciidoctor.Options class, there is org.asciidoctor.Attributes class, which can be used for setting attributes.

render methods are overloaded, so we can pass org.asciidoctor.Options as parameter instead of java.util.Map.

Example of using Options and Attributes class instead of Map.

But asciidoctor-java-integration also provides two fluent interfaces to create these maps and classes in a more readable form.

org.asciidoctor.AttributesBuilder is provided for creating required attributes set, and org.asciidoctor.OptionsBuilder can be used for options. Previous example but using these classes looks like:

Example setting attributes and options with map
Example setting attributes and options with classes

Document Header

readDocumentHeader retrieve information from the header of an AsciiDoc document without parsing or rendering the entire document. This method returns an instance of org.asciidoctor.DocumentHeader with all information from the header filled.

AsciiDoc document with header information
Retrieving some of header information
  1. prints "Sample Document"

  2. prints "Doc Writer"

  3. prints "doc.writer@asciidoc.org"

  4. prints "Doc Writer"

  5. prints "2013-05-20"

  6. prints "1.0"

  7. prints "First draft"

Document structure

readDocumentStructure provides easy and useful way of parsing asciidoc file into the structured object. First of all it gathers exactly the same information as readDocumentHeader and puts it in header filed of StructuredDocument object. Actual content of the file is split into separate ContentParts based on blocks of the content.

There are few possible use cases of using this feature, please consider following examples:

AsciiDoc document with two blocks defined by section titles

Each section defines new content part. List of all parts can be get by getParts method on StructuredDocument. Each part will than contain of title (ie. "Section one") and rendered text content as html.

Print content of each part
AsciiDoc document with two blocks defined by styles

This way you can then use methods like getPartByStyle to retrieve particular content parts.

Retrieve content part by style

Really nice thing about it is possibility to parse images to Image object that you can use later to embed in html page directly from your java code or manipulate in any other way.

Define images

to get a list of images defined in the document and then to process images:

Retrieve image information

As of final example consider following complete use case:

AsciiDoc document with product definition