AsciiDoc formatted content file for JBake.org

test.ad

title=AsciiDoc Test
type=post
tags=asciidoc
date=2013-07-29
status=published
~~~~~~
= Enjoy the magic of Asciidoctor in Java
Alex Soto
2013-04-18
:revdate: 2013-04-18 21:43:51 -0600
:awestruct-tags: [announcement, plugin]
:asciidoc-ref: http://asciidoc.org
:asciidoctor-ref: link:/
:repo-ref: https://github.com/asciidoctor/asciidoctor-java-integration
:issues-ref: https://github.com/asciidoctor/asciidoctor-java-integration/issues

The {repo-ref}[Asciidoctor Java integration] is the official means of using {asciidoctor-ref}[Asciidoctor] to render all your {asciidoc-ref}[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

```xml
<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.

.Method description
[cols="1m,2" options="header"]
|===
|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

```java
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

```java
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

```java
String rendered = asciidoctor.renderFile("docs/sample.adoc", Collections.EMPTY_MAP);
System.out.println(rendered);
```

=== Options

{asciidoctor-ref}[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

```java
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:

.Example setting attributes and options

```java
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+.

.Example of finding all asciidoc

```java
DirectoryWalker directoryWalker = new AsciidocDirectoryWalker("docs");
List<File> asciidocFiles = directoryWalker.scan();
```

== Contributing

You can contribute with patches, better documentation, feature requests, any help you're able to provide.

Great, I only see one problem, read this issue asciidoctor/asciidoctor#502, as you will read Asciidoctor finds a section (doesn't matter the character used) to mark off attributes used by bakers, for example in case of Awestruct uses a block like:

---
layout: default

---
= Document Title

So in Asciidoctor we can ignore all content between ---. But note that in jBake, only a final line of ~ is used which could require a modification on Asciidoctor to adapt to jBake. Could be a possibility to change the header section to be delimited with a block of ~ character instead of only at the end?

I think we should be OK as JBake is stripping out the header and passing just the AsciiDoc formatted body as a string to the Asciidoctor.render method.