Use Arquillian and Docker to verify that AsciidoctorJ works in WildFly

by Maxime Gréau -

We’re excited to announce the newest member of the Asciidoctor family, Docker AsciidoctorJ. The Docker AsciidoctorJ project ensures that AsciidoctorJ can be used by any application deployed to a Java EE application server*.

* For now, only WildFly is tested. Pull requests welcome!

What’s it about?

This project provides:

A Dockerfile

Builds a Docker image that includes WildFly 8.2, AsciidoctorJ 1.5.2 and AsciidoctorJ PDF 1.5.0

Arquillian tests

Uses AsciidoctorJ inside a Docker container to convert AsciiDoc files to HTML and PDF files

AsciidoctorJ WildFly Docker containers managed by Arquillian
Figure 1. The power of Arquillian & Docker for integration testing AsciidoctorJ in WildFly

Learn more!

The following post explains how we execute Arquillian tests for AsciidoctorJ in a WildFly Docker container. We’ll talk about:

Want to know more? Read the full blog post to get all the details.

Asciidoclet 1.5.0 released!

by John Ericksen and Ben Evans -

Following on from the releases of Asciidoctor 1.5.0 and AsciidoctorJ 1.5.0, version 1.5.0 of Asciidoclet has been released with several significant new features, including a new look & feel!

What is Asciidoclet?

Asciidoclet allows Java developers to write Javadoc comments in the portable and rich AsciiDoc syntax instead of HTML.

In short, why write messy Javadoc like this?

/**
 * This class has the following features:
 * <ul>
 *   <li>Support for <strong>foo</strong></li>
 *   <li>Support for bar</li>
 * </ul>
 */
public class Thing implements Something { ... }

…​when you can write tidy Javadoc like this!

/**
 * This class has the following features:
 *
 * - Support for *foo*
 * - Support for bar
 */
public class Thing implements Something { ... }

Much better! Now comments in the source code are much easier to read and write and can be reused outside of Javadoc. Best of all, the HTML generated from Javadoc still looks great (perhaps even better).

Of course, this example just scratches the surface of what’s possible. Tables, lists, code examples with syntax highlighting, links, includes and all of Asciidoctor’s capabilities are available via the lightweight AsciiDoc syntax.

Now, developers can focus on content rather than formatting, and still achieve a beautiful end result.

Artifact information

Artifact information (jCenter @ Bintray)
Group Id Artifact Id Version Download

org.asciidoctor

asciidoclet

1.5.0

pom jar javadoc (jar) sources (jar)
Artifact information (Maven Central)
Group Id Artifact Id Version Download

org.asciidoctor

asciidoclet

1.5.0

pom jar javadoc (jar) sources (jar)

Installing

In Maven, just add the Asciidoclet doclet name and artifact to the maven-javadoc-plugin declaration:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>2.9</version>
  <executions>
    <execution>
      <goals>
        <goal>jar</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <doclet>org.asciidoctor.Asciidoclet</doclet>
    <docletArtifact>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoclet</artifactId>
      <version>1.5.0</version>
    </docletArtifact>
  </configuration>
</plugin>

See the Asciidoclet guide for examples that apply to other build systems and all the available doclet options.

Release highlights

Built on Asciidoctor 1.5.0

Asciidoclet inherits all of the improvements from Asciidoctor 1.5.0 and AsciidoctorJ 1.5.0.

Asciidoctor 1.5.0 introduced some syntax changes. Please refer to the migration guide for details about how to migrate your content.

Improved stylesheets

Asciidoclet includes a default stylesheet with styles from Asciidoctor 1.5.0. This means that AsciiDoc content in the Javadoc is rendered with a similar look and feel to Asciidoctor in other environments.

Javadoc output
Figure 1. Example Javadoc using the Java 8-derived stylesheet

Javadoc’s HTML output varies between releases of the Java platform, so Asciidoclet selects an appropriate stylesheet based on the Java version it is running under:

  • For Java 7 & 8, a stylesheet based on the default Java 8 Javadoc stylesheet is used.

  • For Java 5 & 6, the stylesheet is based on the Java 6 Javadoc stylesheet.

If you want to use your own stylesheet, you can still do this by using Javadoc’s -stylesheetfile option.

AsciiDoc overview files

Javadoc’s -overview option lets you specify an HTML file that will be used as the overview or index page in the generated documentation. This is especially useful for larger projects, where the overview can provide users with a useful introduction and help them to navigate the API.

Asciidoclet now supports overview files written in AsciiDoc as well, with full support for AsciiDoc features such as includes and document attributes. Overview files named *.adoc, *.ad, *.asciidoc or *.txt are processed by Asciidoclet. Other files are assumed to be HTML, and will be processed by Javadoc’s standard doclet.

Document attributes

Asciidoclet now fully supports Asciidoctor’s document attributes. These are one of Asciidoctor’s most powerful features. Document attributes are parameters that can be passed to Asciidoctor to affect how the final output is generated.

Attributes are specified using one or more -a (or --attribute) options when running Asciidoclet. The --attributes-file option reads attributes from an AsciiDoc file. The attributes are passed to Asciidoctor when it renders Javadoc comments.

Here are some examples of how document attributes might be useful in your Javadoc.

Variable substitution

Attribute references in Javadoc comments or overview files are replaced with attribute values:

/**
 * {product-name} will change your life!
 * @version {version}
 */

When the doclet is run with -a product-name=Foo -a version=1.0, Asciidoctor replaces all {product-name} and {version} attribute references with the given values in the generated HTML output. This makes it very simple to inject values into the Javadoc, without changing the source.

Conditional inclusion

AsciiDoc’s conditional directives can selectively include content based on the presence or absence of attributes. This is useful when the same AsciiDoc source is used in different environments.

For example, if you wanted to reuse the same AsciiDoc content in your Javadoc overview page and your web site, but with some differences, you can use attributes to tell Asciidoctor when certain content should be included:

= Documentation for the Foo project

ifdef::javadoc[]
// content that should only appear in Javadoc
endif::javadoc[]

ifdef::my-website[]
// content that should only appear on the web site
endif::my-website[]

Asciidoclet automatically sets the javadoc attribute when it runs, so Javadoc-only content can easily be selected. You can of course define your own attributes as well.

Java and Ruby extension support

Asciidoctor can be extended using Java or Ruby libraries, and Asciidoclet inherits this capability as well.

  • Java extensions are loaded automatically when they are made available in the classpath, using AsciidoctorJ’s Extension SPI.

  • Ruby libraries (Gems) are loaded using the -r (or --require) option.

When using the --require option, we recommend specifying the --gem-path option as well to explicitly set the location of installed gems. Doing so ensures that your build remains portable and reproducible. You can use the gem-maven-plugin to install gems directly into your build directory.

Many extensions are available, but one that is probably most useful for Javadoc authors is Asciidoctor Diagram. Let’s see how it can be used with Asciidoclet.

Embedding diagrams in Javadoc

Asciidoctor Diagram is a popular Asciidoctor extension that lets you embed plain text diagram descriptions in your AsciiDoc source, which get rendered to images when Asciidoctor runs. This can be extremely valuable in Javadoc for describing the architecture or behavior implemeted by the software.

Here’s an example of a Javadoc comment containing a PlantUML sequence diagram:

/**
 * This class implements the following protocol:
 *
 * [plantuml]
 * ....
 * Alice -> Bob: Authentication Request
 * Bob --> Alice: Authentication Response
 *
 * Alice -> Bob: Another authentication Request
 * Alice <-- Bob: another authentication Response
 * ....
 */
public class AuthServer { ... }

Here’s how the diagram above appears in the Javadoc output:

Example output using Asciidoctor Diagram
Figure 2. Example output using Asciidoctor Diagram

Not bad! Developers can easily view and update diagrams in plain text, and users reading the Javadoc will see nicely rendered images.

Many other types of diagrams are supported, including Graphviz, blockdiag and ditaa. See the documentation for Asciidoctor Diagram for more examples.

To enable Asciidoctor Diagram support in Asciidoclet:

  1. Install the Asciidoctor Diagram gem, asciidoctor-diagram:

    $ gem install asciidoctor-diagram

  2. Run Asciidoclet with the following doclet options:

    --require asciidoctor-diagram
--gem-path ${env.GEM_PATH} (1)
--attribute data-uri (2)
    1 The --gem-path ${env.GEM_PATH} option tells Asciidoctor’s JRuby runtime where to find gems when using --require (effectively setting the $GEM_PATH environment variable internally).
    2 The data-uri attribute is required so that the image data is embedded inside the generated HTML files.[1]

  3. Admire the beautiful diagrams adorning your Javadoc!

Thanks!

We hope this new version makes your Javadocs even better. We appreciate everyone who has contributed to Asciidoclet. If you have ideas about how to improve on it, ideas and pull requests are always welcome via the repository on GitHub.

1. Without the data-uri attribute, Asciidoctor Diagram writes image files to a location that doesn’t line up with the generated HTML. This problem is being addressed in Asciidoctor Diagram at the time of writing. Refer to issue #39 for details.

Asciidoctor.js 1.5.0 released to Bower and npm!

by Guillaume Grossetie and Anthonny Quérouil -

The release train is on the move! Version 1.5.0 of Asciidoctor.js has been released and is now available in Bower and npm. This release is an important step toward making Asciidoctor.js widely available to the JavaScript ecosystem.

Bower and npm 
Asciidoctor in JavaScript.
It was a dream.
Then it was a prototype.
Now, it’s the real deal.
What is Asciidoctor.js?

Asciidoctor.js is the official library for using Asciidoctor in JavaScript. It shares the same source code as Asciidoctor and is transcompiled to JavaScript using Opal. With Asciidoctor.js, you can convert AsciiDoc content or analyze the structure of a parsed AsciiDoc document from JavaScript.

When upgrading to Asciidoctor 1.5.0, please refer to the migration guide for details about how to migrate your content.

Release highlights

Asciidoctor.js is Asciidoctor

As mentioned in the release notes for Asciidoctor 1.5.0, we worked hard to align Asciidoctor.js (JavaScript) and Asciidoctor core (Ruby). That means you can expect Asciidoctor.js to parse and convert documents just like the original. Even includes work!

Getting certain features to work, like includes, requires special consideration because JavaScript is a different environment than Ruby and there are even key variations between JavaScript environments!

For example, reading an include file in Ruby is just a matter of using the normal Ruby IO API. In a browser environment, we have to use XMLHttpRequest (i.e., Ajax) as the IO API instead. If Asciidoctor.js is running on Node.js, we have to use the Node IO API, fs.readSync(), to make it work.

Rest assured we’re continuing to work on smoothing any differences to bring all the great features of Asciidoctor core to JavaScript.

Read on to learn how to get your hands on Asciidoctor.js!

Using Asciidoctor.js is easier than ever before

If you are a frontend or backend JavaScript developer, you’re only one command away from getting the latest version of Asciidoctor.js

Bower package

Installing Asciidoctor.js with Bower
$ bower install asciidoctor.js --save
The optional --save flag automatically adds the package to your project’s dependencies.

Once the package installed, you can add the following script tag to your HTML page:

<script src="bower_components/asciidoctor.js/dist/asciidoctor-all.min.js"></script>

The asciidoctor-all.min.js is a minified version and includes Asciidoctor core, extensions API and Opal.

Here is a simple example that converts AsciiDoc to HTML5 using the doctype: 'inline' option and showtitle attribute:

var asciidoc = "http://asciidoctor.org[*Asciidoctor*] " +
    "running on https://opalrb.com[_Opal_] " +
    "brings AsciiDoc to the browser!";
var options = Opal.hash2(['doctype', 'attributes'], {doctype: 'inline', attributes: ['showtitle']});
var html = Opal.Asciidoctor.$convert(asciidoc, options);
console.log(html);

See the Front-end development guide to learn more about the Bower package.

npm package

Installing Asciidoctor.js with npm
$ npm install asciidoctor.js --save
The optional --save flag automatically adds the package to your project’s dependencies.

Once the package is installed, the first thing to do is to load the asciidoctor.js module using require, then you’re ready to start using the API:

sample.js
var asciidoctor = require('asciidoctor.js')(); (1)
var opal = asciidoctor.Opal; (2)

var processor = null;
var useExtensions = true;

if (useExtensions) {
  processor = asciidoctor.Asciidoctor(true); (3)
}
else {
  processor = asciidoctor.Asciidoctor(); (4)
}

var content = "http://asciidoctor.org[*Asciidoctor*] " +
    "running on https://opalrb.com[_Opal_] " +
    "brings AsciiDoc to Node.js!";
var options = opal.hash2(
    ['doctype', 'attributes'],
    {doctype: 'inline', attributes: ['showtitle']});
var html = processor.$convert(content, options); (5)
console.log(html); (6)
1 Load the Asciidoctor.js library
2 Retrieve and alias the top-level Opal namespace
3 Instantiate Asciidoctor with extensions enabled
4 Instantiate Asciidoctor without extensions
5 Convert AsciiDoc content to HTML5 using Asciidoctor.js
6 Print the HTML5 output to the console

Save the file as sample.js and run it using the node command:

$ node sample.js

You should see the following output in your terminal:

<a href="http://asciidoctor.org"><strong>Asciidoctor</strong></a> running on <a href="https://opalrb.com"><em>Opal</em></a> brings AsciiDoc to Node.js!</p>
To be successful with Asciidoctor.js, it’s important to understand how to work with Ruby objects in the JavaScript environment. We recommend that you browse the Opal documentation to learn how method names are mapped and what data types it expects.

See the Back-end development guide to learn more about the npm package.

Asciidoctor.js is heating up on Node

Node.js is where the hottest JavaScript is happening and npm is the package manager that manages and distributes that hotness. We wanted Asciidoctor.js to be a part of this ecosystem. We also needed it there to start building tools. That’s why we took the first step of packaging Asciidoctor.js as an npm package…​in fact, several! Asciidoctor now has a new playground!

Here are the npm packages that are published:

asciidoctor.js

the main npm package for Asciidoctor.js

grunt-asciidoctor

an npm package for processing AsciiDoc source files in your Grunt project

Here’s how the community is playing with these packages already:

asciidoc-preview (Atom Editor)

A plugin for Atom that shows you a preview of your document while you type!

asciidoc-preview (Brackets Editor)

An extension for Brackets that shows you a preview of your document while you type!

grunt-asciidoctor-assemble

a static website generator for Grunt by @tedbergeron

Of course there are still challenges, but we’ll solve them. Head over to the Asciidoctor.js project to get involved.

Let us play this new game!

Asciidoctor.js on the JVM

You read that right. The browser ain’t the only JavaScript game in town. (And we’re not talking about JavaScript engines that have escaped from the browser, like Node.js.) We’re talking about the most polyglot of polyglot runtimes, the JVM.

Alex Soto is working at getting Asciidoctor.js integrated into AsciidoctorJ so you can use it on the JVM using Nashorn, dynjs and other JavaScript engines that run on it. The AsciidocFX project is already using Asciidoctor.js on Nashorn, so it’s more than just an idea!

There are still several challenges to tackle to ensure Asciidoctor.js runs smoothly on the JVM, such as getting includes working. Head over to the AsciidoctorJ project to get involved and help make it happen!

Acknowledgments

The alignment of Asciidoctor.js with Asciidoctor core was a major effort. It required input from a lot of people and they really pulled together to meet this challenge.

We want to especially thank the Opal developers, notably Adam Beynon, meh and Elia Schito, for making Asciidoctor.js happen. They were very responsive to our effort, making changes and fixes to Opal and generally providing input that allowed us to continuously move forward.

We also want to thank Anthonny Quérouil for crafting a Grunt build to compile, aggregate and compress Asciidoctor.js and for helping to get the artifacts published to Bower and npm.

Thanks to everyone who tested Asciidoctor.js, either directly or by using the tools. Your participation has helped Asciidoctor.js become the real deal!

If you have questions or feedback, we encourage you to participate in the discussion list. Talk to you there!

Asciidoctor Maven plugin 1.5.0 released!

by Dan Allen -

Storm in Desert

The West may still be suffering from a dry spell, but we’re excited to shower Maven users with the release of version 1.5.0 of the Asciidoctor Maven plugin to Maven Central and jCenter!

This version brings all the improvements from Asciidoctor 1.5.0 and AsciidoctorJ 1.5.0, plus enhancements to the site plugin. Like other versions before it, this plugin is based on the same version of the Asciidoctor and AsciidoctorJ projects (now using semantic versioning) — 1.5.0.

Artifact information

Artifact information (jCenter @ Bintray)
Group Id Artifact Id Version Download

org.asciidoctor

asciidoctor-maven-plugin

1.5.0

pom jar javadoc (jar) sources (jar)
Artifact information (Maven Central)
Group Id Artifact Id Version Download

org.asciidoctor

asciidoctor-maven-plugin

1.5.0

pom jar javadoc (jar) sources (jar)

Installing or upgrading

Installing or upgrading to 1.5.0 is simple. Just update the version in your pom.xml. All necessary dependencies will be pulled in via Maven’s dependency management.

<plugins>
  <plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.0</version>
  </plugin>
</plugins>

Refer to the example project to copy-paste your way to greatness!

When upgrading to Asciidoctor 1.5.0, please refer to the migration guide for details about how to migrate your content.

Please refer to the manual for the Asciidoctor Maven plugin for information about configuration options and other capabilities of the plugin.

Release highlights

Published the jCenter

The Asciidoctor Maven plugin is now published to Bintray’s jCenter! The means you can find the plugin more easily and its published to the future destination of binaries on the web. You can elect to get notified by Bintray when new versions are available.

Copy non-AsciiDoc files to output directory (#67)

The Asciidoctor Maven plugin now copies non-AsciiDoc files to the output directory so you can put resources, such as images or stylesheets, in the AsciiDoc source folder. This change aligns the behavior of the Asciidoctor Maven plugin with the behavior of Gradle plugin.

Add configuration for setting the gem path and loading additional gems (#109)

You can now specify the location to one or more gem installation directories (i.e., GEM_PATH) using the gemPath configuration option. The main purpose of this setting is to load additional Ruby libraries not packaged in AsciidoctorJ, such as asciidoctor-diagram. You can load additional libraries (absolute path, relative path or gem name) using the require configuration option.

Here’s an example of how to use that configuration within the plugin stanza in your pom.xml:

<configuration>
  <gemPath>${project.build.directory}/gems-provided</gemPath>
  <requires>
    <require>asciidoctor-diagram</require>
  </requires>
</configuration>
You’ll need to use the gem-maven-plugin if you want to download and install gems automatically as part of your build. Refer to the example project to copy-paste your way to greatness!
Configure AsciidoctorJ in isolation (#111)

Prior to 1.5.0, the Maven plugin would allow JRuby to see gems installed external to the project if you had the GEM_HOME or GEM_PATH environment defined (typical if you’re using RVM). This could result in non-reproducible builds.

We’ve gone part of the way of solving this problem by clearing the GEM_PATH environment variable unless it’s specified in the plugin configuration. However, the GEM_HOME environment variable won’t be cleared properly until AsciidoctorJ 1.5.1. In the interim, we issue a warning in the build if GEM_HOME is set to a path outside the build so that you know to reset the value manually (e.g., by running rvm use system).

Properly handle false and empty attribute values (#93)

There was a regression in 0.1.4 that treated both false and empty attribute values as true. Maven needs hand holding to properly convert these values. You can now use an empty string value and it will mean enable the attribute or a false value and it will mean disable the attribute. For example:

<configuration>
  <attributes>
    <toc/>
    <linkcss>false</linkcss>
  </attributes>
</configuration>

This configuration is the equivalent of the following commandline arguments to Asciidoctor:

-a toc -a linkcss!
Generate XHTML in the Maven site plugin (#61)

One of the most important improvements in Asciidoctor 1.5.0 was the addition of the XHTML backend. Simply put, this backend emits XHTML5 (XML-compliant HTML5) instead of the shorthand HTML5 that is the norm. The main reason this backend was added was to fix the behavior of the site module in the Asciidoctor Maven plugin. The XML parser that the Maven site plugin uses will thank you!

EPUB3 output

AsciidoctorJ provides integration with the Asciidoctor EPUB3 converter out of the box. That means you can use it in the Maven plugin without having to declare any additional dependencies. Just set the backend to epub3 and you’re ready to go!

The EPUB3 converter is currently alpha. Expect some glitches while the dust settles!

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

Acknowledgments

Thank you to all the contributors for helping out with this release, and for everyone involved in making Asciidoctor an awesome documentation toolchain and community! We particularly want to that the developers of the Asciidoctor Gradle plugin for giving us lots of ideas for how to make the Maven plugin great!

Enjoy building great documentation!

Asciidoctor Gradle plugin 1.5.0 released!

by Andres Almiray -

It took us longer than what we hoped but Asciidoctor Gradle plugin version 1.5.0 is finally here! The Asciidoctor Gradle plugin is based on AsciidoctorJ and, for the first time, aligns with its version numbering scheme.

Here’s the basic setup to get you started:

The plugin tracks the AsciidoctorJ version starting with this release, hence the jump from 0.7.3 to 1.5.0. There are many goodies inside Asciidoctor 1.5.0 as explained in the release notes, but perhaps the most interesting one for Gradle users is the capability to write custom extensions (or tag handlers if you will) using Groovy. You can include extensions just by placing their containing JAR in the classpath, or you can write them directly in your Gradle build, by placing the code inside buildSrc. There’s a trivial example of the latest option at github.com/aalmiray/asciidoctor-piglatin-example.

Other features found in this release are:

  • ability to load Ruby-based extensions using the requires property on AsciidoctorTask.

  • ability to set the gem installation path using the gemPath property on AsciidoctorTask.

Developers are advised to upgrade as soon as possible. Be mindful of the compatibility issues raised at the plugins’ readme. Do not forget to review the changes brought by Asciidoctor 1.5.0 found at the migration guide.

Hackergarten
Figure 1. Basel Hackergarten @ Canoo July 24th

The development team would like to thank participants of various Hackergarten sessions, both in Switzerland and abroad. Several issues and features have been contributed during those sessions. We couldn’t have done it without your help. Also, thank you to all the contributors for helping out.

Go forth and make great (and Groovy) documentation once again!

Upgrading to 1.5.0 (recommended) is simple. Just update the version in your Gradle build file. All necessary dependencies should be pulled in via Gradle.

When upgrading to Asciidoctor 1.5.0, please refer to the migration guide for details about how to migrate your content.

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

  • 2 of 7