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();