Asciidoctor Java integration 0.1.2 released!

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.

In this new release, the following issues has been resolved:

  • Upgraded Asciidoctor gem to 0.1.2. Resolves #17.

  • Reduced startup time by tuning JRuby. Resolves #15, documented in optimization.

  • Renamed AsciidocDirectoryWalker class to AsciiDocDirectoryWalker to follow naming conventions. Resolves #12.

    If you’re currently using AsciidocDirectoryWalker, you’ll need to refactor your code to reflect this name change.

  • Promoted backend and doctype attributes to options in the fluent API. Resolves #11.

  • Added a render method which takes a Reader and Writer interface as input and output content. Resolves #9, documented in usage.

  • Changed Asciidoctor#renderFile method parameter type from java.lang.String to java.io.File.

    If you’re currently using the Asciidoctor#renderFile method, you’ll need to refactor your code to reflect this type change.

For more information, visit the Asciidoctor Java integration project on GitHub.

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!

Asciidoctor 0.1.2 released!

by Dan Allen -

We’re proud to announce the release of Asciidoctor 0.1.2!

Asciidoctor is an open source text processor and publishing toolchain for converting AsciiDoc markup into HTML 5, DocBook 4.5 and other formats.

The focus of this release cycle was on:

The valuable feedback we’ve received has helped bring Asciidoctor to 99% compliance with the AsciiDoc syntax. The improvements have also given Asciidoctor a 28% boost in speed, now more than 30x as fast as AsciiDoc.

Key improvements

default stylesheet

Asciidoctor now ships a default stylesheet! This stylesheet gives documents a unique, modern and elegant look and feel out of the box. To learn how to use it, read the stylesheet section of How do I render a document?. Visit http://themes.asciidoctor.org to a preview the default stylesheet and other themes created using the Asciidoctor stylesheet factory. Resolves issues #76 and #165.

docinfo files

Supplemental document header files (i.e., docinfo files) are now included in the rendered output when enabled. These files are used to include custom content into the header of the HTML or DocBook output. Resolves issues #116 and #193.

leveloffset

The leveloffset attribute is now supported. This attribute allows several standalone documents to be combined as a master document. Resolves issue #212.

partial includes

The include macro can now be used to include select regions of a file by line numbers, line ranges or tagged regions. This enhancement to the include macro is unique to Asciidoctor. Resolves issue #226.

footnotes in embedded mode

Footnotes are now rendered at the bottom of the output in embedded mode (when the header and footer are disabled), such as on GitHub or in a page generated by Awestruct. Resolves issue #206.

table of contents macro

Support has been added for the toc macro, which allows you to place the toc anywhere in the document. This feature makes it possible to include a toc in the document when in embedded mode, such as on GitHub or in a page generated by Awestruct. Resolves issues #269 and #221.

audio and video macros

Macros have been added to output HTML 5 audio and video tags. These macros parallel the block image macro. Resolves issue #155.

safe mode and embedded attributes

The attributes safe-mode-level, safe-mode-name and safe-mode-%name% are now assigned to match the active safe mode. The attribute embedded is assigned to indicate the document is rendered using the embedded document template. Resolves issue #244.

multiple authors

You can now specify multiple authors in the header of the document, separated by semi-colons. In the DocBook backend, the authors are listed in an authorgroup element in the document info section. This feature is unique to Asciidoctor. Resolves issue #223.

email macro

The inline email address and the inline mailto macro are now recognized. Resolves issue #213.

secure paths

The path resolution logic was simply too fragile as a result of relying on Ruby core libraries. The code has been completely rewritten so that paths are properly normalized and secured, with loads of tests to back it up.

custom block substitutions

Substitution groups applied to block content can now be customized using the subs block attribute. Resolves issue #220.

masquerading blocks and paragraphs

The open block and paragraphs can now masquerade as any style of block. Masquerading is also available for other blocks, where applicable. This was one of the weakest areas of Asciidoctor, now fully compliant (and even a little extra). Resolves issue #187.

In order to implement full support for masquerading blocks, paragraphs and custom block substitutions, the main block parsing code had to be reworked. The refactoring not only cleaned up the code, but laid the foundation necessary to implement block filters and other extensions.

Some of the improvements to Asciidoctor have resolved issues inherent in AsciiDoc. Fortunately, AsciiDoc is configurable enough that these issues can be "ported" to AsciiDoc without changing the core. We now maintain and ship an AsciiDoc configuration file, asciidoc.conf, that makes AsciiDoc conform to Asciidoctor’s behavior and enhancements. Resolves issue #257.

The full list of new features, enhancements and patches implemented in this release can be viewed by filtering on the 0.1.2 milestone in the issue tracker.

New website and documentation

You’re looking at it!

During the 0.1.2 release cycle, we created a proper website for Asciidoctor and focused on getting the user documentation started. Both the website and documentation are, of course, written in AsciiDoc.

Sarah White has taken on the initiative of untangling information in the AsciiDoc user guide and man pages and converting it to something consumable so users can get started quickly with the AsciiDoc and Asciidoctor toolchains.

I wrote up an introduction to AsciiDoc, an AsciiDoc writer’s guide and an AsciiDoc syntax quick reference to reveal the elegance of the AsciiDoc syntax and get writers the information they need to be productive and proficient with AsciiDoc. I summarized this information in an article titled The Zen of Writing (Ascii)Docs, published in the April issue of NFJS, The Magazine (also produced from articles written in AsciiDoc).

Look for more details about the website and documentation in a future news post.

Thanks!

The amount of participation in the Asciidoctor project, particularly around the integrations, has increased tremendously since the last release. Asciidoctor 0.1.1 crossed the 10,000 downloads mark prior to this release. We look forward to 0.1.2 breaking the next 10,000.

We’re very grateful to everyone who participates, especially those who contribute and spread the word :) We’d especially like to thank the following people for their contributions and feedback:

Together, we’re making documentation easy, fun and rewarding!

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.

  • 6 of 7