Enjoy the magic of Asciidoctor in Java
by -
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.
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-java-integration</artifactId>
<version>${asciidoctor.version}</version> (1)
</dependency>
</dependencies>| 1 | As this library tracks the version of Asciidoctor, you can use which every 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.
| Name | Description |
|---|---|
|
Parse the AsciiDoc content into a Document and render it to the specified backend format. |
|
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.
import static org.asciidoctor.Asciidoctor.Factory.create;
import org.asciidoctor.Asciidoctor;
Asciidoctor asciidoctor = create();And then we can call render methods depending on our requirements.
String rendered = asciidoctor.render("*This* is it.", Collections.EMPTY_MAP);
System.out.println(rendered);But also you can render the content of a file.
String rendered = asciidoctor.renderFile("docs/sample.adoc", Collections.EMPTY_MAP);
System.out.println(rendered);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 we can set all these options.
Map<String, Object> attributes = new HashMap<String, Object>();
attributes.put("backend", "docbook");
Map<String, Object> options = new HashMap<String, Object>();
options.put("in_place", true);
options.put("attributes", attributes);
String render = asciidoctor.renderFile("docs/sample.adoc", options);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.
But asciidoctor-java-integration also provides two builder classes to create these maps in a more readable form.
AttributesBuilder is provided for creating a map with required attributes set, and OptionsBuilder can be used for options. Previous example but using these classes looks like:
import static org.asciidoctor.AttributesBuilder.attributes;
import static org.asciidoctor.OptionsBuilder.options;
...
Map<String, Object> attributes = attributes().backend("docbook").asMap();
Map<String, Object> options = options().inPlace(true).attributes(attributes).asMap();
String render = asciidoctor.renderFile("docs/sample.adoc", options);Utilities
A utility class for searching all asciidoc files present in a root folder and all its subfolders is given. In fact it finds all files that end up with .asc, .asciidoc, .ad or .adoc. This class is AsciidocDirectoryWalker.
DirectoryWalker directoryWalker = new AsciidocDirectoryWalker("docs");
List<File> asciidocFiles = directoryWalker.scan();