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.
-
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.
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.
And then we can call render
methods depending on our requirements.
But also you can render the content of a file.
Or a list of Asciidoc 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.
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.
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.
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
.
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:
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.
-
prints "Sample Document"
-
prints "Doc Writer"
-
prints "doc.writer@asciidoc.org"
-
prints "Doc Writer"
-
prints "2013-05-20"
-
prints "1.0"
-
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:
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.
This way you can then use methods like getPartByStyle to retrieve particular content parts.
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.
to get a list of images defined in the document and then to process images:
As of final example consider following complete use case: