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
... <dependencies> <dependency> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-java-integration</artifactId> <version>${asciidoctor.version}</version> <1> ... </dependency> </dependencies> ... |
-
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.
Also a factory method is provided to create an instance of
Asciidoctor interface.Creation 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.Rendering a String
... String rendered = asciidoctor.render("*This* is it.", Collections.EMPTY_MAP); System.out.println(rendered); ... |
But also you can render the content of a file.
Rendering a File
... String rendered = asciidoctor.renderFile("target/test-classes/rendersample.asciidoc", 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.Example of using in_place Option and backend Attribute
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("target/test-classes/rendersample.asciidoc", 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:Example setting attributes and options
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("target/test-classes/rendersample.asciidoc", 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.Example of finding all asciidoc
DirectoryWalker directoryWalker = new AsciidocDirectoryWalker("target/test-classes/src"); List<File> asciidocFiles = directoryWalker.scan(); |
We keep learning,
Alex.
Cold, cold heart, Hard done by you, Some things look better, baby, Just passing through (Sacrifice - Elton John)
http://www.youtube.com/watch?v=NrLkTZrPZA4
