Asciidoctor Maven plugin 0.1.2 released!

by Jason Porter -

Following the tradition of quick updates shortly after the release of Asciidoctor, I’d like to announce the release of versions 0.1.2 and 0.1.1.1 of the Asciidoctor Maven plugin!

These releases are based on Asciidoctor 0.1.2 and 0.1.1, respectively. Both versions of the plugin have been migrated to the newly released Asciidoctor Java integration, and thus supports all the options exposed through that library.

Plugin artifact information
Group ID Artifact ID Latest versions Download

org.asciidoctor

asciidoctor-maven-plugin

0.1.2

pom jar

org.asciidoctor

asciidoctor-maven-plugin

0.1.1.1

pom jar

Upgrading to 0.1.2 (recommended) or 0.1.1.1 is simple. Just update the version in your Maven POM. All necessary dependencies should be pulled in via Maven.

For more information about issues fixed in this release, please see the 0.1.2 milestone in the issue tracker!

Enjoy the magic of Asciidoctor in Java

by Alex Soto -

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

Table 1. Method description
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
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("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.

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("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
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
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.

Introducing the Asciidoctor Maven plugin

by Jason Porter -

I’d like to introduce you to the easiest way to use AsciiDoc from Maven, the Asciidoctor Maven plugin!

Plugin artifact information
Group ID Artifact ID Latest version Download

org.asciidoctor

asciidoctor-maven-plugin

0.1.1

pom jar

This plugin is a great option for projects interested in using AsciiDoc to author documentation, or any part of this project utilizing AsciiDoc. Best of all, it’s already available from Maven Central.

How it works

The Maven plugin loads JRuby, scans for AsciiDoc files in the specified directory, then invokes Asciidoctor to render them. You have the option of rendering the files to HTML 5 and DocBook 4.5.

Setup and usage

Adding this plugin to your Maven POM is simple. Just add this plugin declaration:

pom.xml fragment: Asciidoctor Maven plugin configuration
<plugin>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-maven-plugin</artifactId>
  <version>0.1.1</version>
  <executions>
    <execution>
      <id>render-asciidoc</id>
      <phase>generate-resources</phase>
      <goals>
        <goal>process-asciidoc</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
      <sourceDirectory>docs</sourceDirectory>
      <outputDirectory>target/docbook/en-US</outputDirectory>
      <backend>docbook</backend>
  </configuration>
</plugin>

Execution is handled by Maven when you execute a build.

You can find more detailed information about setup and usage in the README located in the project’s repository on GitHub.

Versioning

The version of the Maven plugin will track the version of Asciidoctor. In most cases, the version number will match the Asciidoctor version (e.g., 0.1.1). If an interim fix needs to be made to the plugin, an additional number will be added to the end of the Asciidoctor version number (e.g., 0.1.1.1).

Future

Currently, the plugin uses its own JRuby integration to invoke Asciidoctor (which is written in Ruby). The next version (roadmap) will use the newly-released Asciidoctor Java integration to streamline the hand off and simplify maintenance of the project.

In conjunction with the change to use the Asciidoctor Java integration internally, new configuration options will be added. One of those options will allow you to pass AsciiDoc attributes to the renderer. AsciiDoc attributes control options such as adding a table of contents, turning on section numbering and configuring the source highlighter.

Contributing

We’re always open for patches, better documentation, feature requests, evangelizing or any help you’re able to provide.

  • 2 of 2