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.

A new resource for AsciiDoc

by Dan Allen -

AsciiDoc is an excellent tool for writing documentation, but there’s simply not enough information about it.

Today, I’m excited to announce a new resource for AsciiDoc, asciidoctor.org. In addition to serving as the project page for the Asciidoctor project and its integrations, this website helps promote AsciiDoc through education and advocacy.

dawn
The dawn of a new era Photo credit: bartvandorp

The key highlight of the site is a collection of new AsciiDoc guides:

The purpose of these guides is to answer your questions about AsciiDoc and get you familiar with the syntax quickly. They present AsciiDoc by following a recommended set of conventions to help you create more consistent documents and maximize your writing productivity.

If you see a change you want to make, contributing to the guides is easy!

The guides are written in AsciiDoc and hosted on GitHub. If you see a change you want to make in one of the guides, just look for the Edit button in the right-hand column and click on it. That will take you to an editor on GitHub where you can make the change and submit it as a pull request.

Alternatively, you can clone the project, make the change locally, commit it, then send a pull request in the usual way.

Once the change is merged into the master branch, it gets published automatically.

I hope you find the guides useful, and I look forward to your feedback. Together, we can take the agony out of writing documentation!

AsciiDoc, powered by Asciidoctor, returns to GitHub and its 5+ million repositories

by Dan Allen -

Since early December and throughout the holidays, GitHub’s Ryan Waldron, Red Hat’s Dan Allen and other contributors have collaborated on Asciidoctor (project site, code repository), a new open source implementation of AsciiDoc written purely in Ruby[1].

The implementation kicked off with two core goals in mind:

  1. Improve the rendering of AsciiDoc source files in git repositories and gists on GitHub

  2. Bring AsciiDoc to the Ruby world by offering the first compliant Ruby port of the markup language

After a lot of hard work and a thorough security audit, we’re thrilled to announce that…​

Note Asciidoctor is now deployed to render AsciiDoc markup in any of the 5 million+ repositories on GitHub.

Asciidoctor 0.1.0 is also available on rubygems.org and can be installed locally via RubyGems (gem install asciidoctor).

About AsciiDoc

AsciiDoc is a lightweight markup language akin to Markdown. Going beyond Markdown, AsciiDoc supports all the structural elements necessary for drafting articles, technical manuals and books. Several O’Reilly authors, including Matthew McCullough, Tim Berglund and Matt Neuburg, have used it to write books for that iconic technical library. AsciiDoc is fully capable of serving as a shorthand replacement for DocBook, which it can also output.

DocBook is nice, but (like XML) it is not meant for editing nor for merging changes (by humans). Using AsciiDoc (which translates to DocBook perfectly) is a much easier way of developing.

— Dag Wieers

One way to think of the relationship between AsciiDoc and DocBook is that AsciiDoc is to DocBook as RelaxNG Compact is to XML Schema. With AsciiDoc, you drop the angled-brackets (i.e., XML), but not the semantics.

Here’s an example of a document written in AsciiDoc, shown above the output it produces:

(You don’t want to see how the DocBook looks for this example. Let’s just say, there isn’t enough room on the screen to show it to you.)

Source document

 
= Asciidoctor
Ryan Waldron, Dan Allen

http://asciidoctor.org[Asciidoctor] is a native Ruby processor
for converting AsciiDoc source files and strings into HTML 5,
DocBook 4.5 and other formats.

== Installation

You can install the Asciidoctor RubyGem using the +gem+ command:

 gem install asciidoctor

On Fedora, you can install via an RPM package
(https://bugzilla.redhat.com/show_bug.cgi?id=889011[pending])
using the +yum+ command:

 yum install rubygem-asciidoctor

Now you are ready to start using Asciidoctor!

== Benefits

Asciidoctor is:

* compliant
* fast
* secure
* stable

'Give it a try!'

Rendered HTML Output

Asciidoctor

Ryan Waldron, Dan Allen

Asciidoctor is a native Ruby processor for converting AsciiDoc source files and strings into HTML 5, DocBook 4.5 and other formats.

Installation

You can install the Asciidoctor RubyGem using the gem command:

gem install asciidoctor

On Fedora, you can install via an RPM package (pending) using the yum command:

yum install rubygem-asciidoctor

Now you are ready to start using Asciidoctor!

Benefits

Asciidoctor is:

  • compliant

  • fast

  • secure

  • stable

Give it a try!

The AsciiDoc project, written in Python, was the only implementation of the AsciiDoc syntax…​until the arrival of "the doctor".

The Asciidoctor implementation

Asciidoctor is the first project to implement the AsciiDoc syntax in another language, in this case Ruby. It’s an open source library (MIT licensed) published as a RubyGem to rubygems.org. The project recently moved to the Asciidoctor organization on GitHub to sustain its rapid growth.

While Asciidoctor aims to offer full compliance with the AsciiDoc syntax (with some exceptions, noted in the project README), it’s more than just a clone.

Built-in and custom templates

Asciidoctor uses a set of built-in ERB templates to generate HTML 5 and DocBook 4.5 output that is structurally equivalent to what AsciiDoc produces. Any of these templates can be replaced by a custom template written in any template language available in the Ruby ecosystem. Custom template rendering is handled by the Tilt template abstraction library, a project created by another GitHubber, Ryan Tomayko.

Parser and object model

Leveraging the Ruby stack isn’t the only benefit of Asciidoctor. Unlike the AsciiDoc Python implementation, Asciidoctor parses and renders the source document in discrete steps. This makes rendering the document optional and gives Ruby programs the opportunity to extract, add or replace information in the document by interacting with the document object model Asciidoctor assembles. Developers can use the full power of the Ruby programming language to play with the content in the document.

Performance and security

No coverage of Asciidoctor would be complete without mention of its speed. Despite not being an original goal of the project, Asciidoctor has proven startlingly fast. It loads, parses and renders documents at least 25 times as fast as the Python implementation. That’s good news for developer productivity and good news for GitHub or any server-side application that needs to render AsciiDoc markup. Asciidoctor also offers several levels of security, further justifying its suitability for server-side deployments.

Beyond Ruby

Asciidoctor’s usage is not limited to the Ruby community. Thanks to JRuby, a port of Ruby to the JVM, Asciidoctor can be used inside Java applications as well (and eventually in Java build tools like Apache Maven). Asciidoctor also ships with a command-line interface (cli), written by Red Hat’s Jason Porter. The Asciidoctor cli, asciidoctor, is a drop-in replacement for the asciidoc.py script from the AsciiDoc Python distribution.

The future of Asciidoctor and AsciiDoc

The future is bright for AsciiDoc. Despite being a seasoned, 10-year-old markup language, adoption of AsciiDoc has never been stronger. The developers have lots of ideas about how to improve and extend Asciidoctor, some of which push beyond the AsciiDoc syntax.

  • If you’re interested in using AsciiDoc, head over to GitHub and create a new file in one of your repositories or gists using the file extension .asciidoc or .adoc.

  • If you’re interested in contributing to Asciidoctor, in turn helping to move AsciiDoc forward, your participation and feedback is welcome!

Write docs with pleasure!

This article was composed in AsciiDoc and rendered using Asciidoctor.
1. The Asciidoctor code base emerged from a prototype that GitHub developers created last year to produce the git man pages shown on the git website.
  • 2 of 2