Funding for Asciidoctor

by Dan Allen and Sarah White -

With Asciidoctor, we’re working to shape the future of writing and publishing, particularly in the field of technical documentation. We want people to use open source not only because it’s the best software, but because it’s the best documented software.

We’ve come a long way. We have even bigger plans for the future. To turn our vision into reality, the Asciidoctor project needs funding.

Bountysource

In order to ensure the continued success and sustainability of the Asciidoctor project, we’ve setup an account for Asciidoctor on Salt, the new funding platform from Bountysource. (Bountysource is like Kickstarter for open source projects). You can read more details about this campaign, how it works and our initial goals on the Asciidoctor campaign page.

The Salt platform will enable us to accept financial backing for Asciidoctor from both organizations and individuals and allocate the money the way we think best suits the project. It will also allow us to be completely transparent about how the project is funded. The initial goal is to allow us (Dan and Sarah) to work on Asciidoctor full time.

Asciidoctor growth

Asciidoctor has grown and matured substantially over the last three years. It’s now a critical component of documentation, especially in open source. In order to keep up with the project’s rate of growth, manage the Asciidoctor ecosystem as a whole, and be there to facilitate participation, we need to be able to dedicate more time and attention to this work. We also need to cover current and future infrastructure costs. The more money this campaign raises (on an ongoing basis), the more we can achieve, the more possibilities we can unlock and the greater the impact Asciidoctor can have.

By securing funding, the Asciidoctor project can essentially hire us (Dan and Sarah) to keep it operating smoothly and releasing components more frequently. We love running the Asciidoctor project and we love the community. We want to continue serving the community and doing what we love to make a toolchain writers have always wanted.

Let’s make it happen!

If you have questions or concerns, please don’t hesitate to respond.


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.


Plain-text diagrams take shape in Asciidoctor!

by Pepijn Van Eeckhoudt -

You write in plain text. You code in plain text. How about creating diagrams in plain text too? Now you can using Asciidoctor Diagram!

Introduction

Asciidoctor is a fantastic tool to use when writing technical documentation. It allows you to spend more time focusing on your content rather than struggling with WYSIWYG tools.

One task that still pulls your focus away, and is more difficult than it should be, is integrating technical diagrams into your documents. It involves launching a UML or diagramming tool, pushing pixels around the screen to draw the diagrams, exporting the result to a web-friendly image format and linking to them from your source document. The many benefits that AsciiDoc provides in terms of visual consistency, ease of collaboration, etc. are not available when you are working with diagrams.

All that changes today with the announcement of the Asciidoctor Diagram extension. Asciidoctor Diagram integrates existing plain text syntax diagramming tools into the Asciidoctor processing. That means you can embed the source code for your diagrams directly into your documents!

The first version of Asciidoctor Diagram supports the following diagram languages:

These “lightweight diagram languages” are to graphical diagrams what AsciiDoc is to HTML. Another way of saying it:

language analogy diagram

Your first plain-text diagram

The simplest way to add diagrams to your documents is by using diagram blocks. Just add a listing block to your file using the appropriate syntax name (ditaa, graphviz or plantuml) as the block name (aka style).

[ditaa]
----
                   +-------------+
                   | Asciidoctor |-------+
                   |  Diagram    |       |
                   +-------------+       | PNG out
                       ^                 |
                       | ditaa in        |
                       |                 v
 +--------+   +--------+----+    /----------------\
 |        | --+ Asciidoctor +--> |                |
 |  Text  |   +-------------+    |Beautiful output|
 |Document|   |   !magic!   |    |                |
 |     {d}|   |             |    |                |
 +---+----+   +-------------+    \----------------/
     :                                   ^
     |          Lots of work             |
     +-----------------------------------+
----

When the Asciidoctor Diagram extension processes this type of block, it will read the body of the block, pass it to the ditaa library, write the resulting image to disk and generate an image block. Here’s how it appears in the rendered document:

sample ditaa diagram

Magic!

Generating one of these images is fairly quick, but if you start adding lots of diagrams to your document the processing time can start adding up. Asciidoctor Diagram optimizes the processing by keeping track of diagram metadata in *.cache files and will only regenerate the images if the diagram source code was modified. This keeps incremental rendering of documents a speedy process.

Controlling the output

By default Asciidoctor Diagram creates PNG images and calculates an output file name automatically based on the diagram source code. This behavior can be overridden using the target and format attributes. You can specify these attributes as the first and second positional attributes or as explicitly named attributes. An SVG file with a specific name a Graphviz diagram can be generated as follows

[graphviz, dot-example, svg]
----
digraph g {
    a -> b
    b -> c
    c -> d
    d -> a
}
----

After the magic happens, you’ll see:

sample graphviz diagram
Asciidoctor Diagram bundles both the ditaa and PlantUML libraries and will use them to generate diagrams. In order to generate diagrams using Graphviz, you must install it separately (meaning the dot command must be available on your PATH).

Asciidoctor Diagram turns the diagram blocks into image blocks and applies any additional attributes. This means you can use the normal Asciidoctor facilities to control the positioning of the generated image. Block titles and IDs can also be assigned in the same way.

[[main-classes]]
.The PlantUML block extension class
[plantuml, sample-plantuml-diagram, alt="Class diagram", width=135, height=118]
----
class BlockProcessor
class PlantUmlBlock
BlockProcessor <|-- PlantUmlBlock
----

Here’s what gets rendered:

Class diagram
The PlantUML block extension class

Including external diagrams

It might not always be desirable to embed the source code for diagrams in your document. External diagrams can also be processed using the block macro syntax. This is very similar to how you typically include images in your documents.

plantuml::classes.txt[format=svg, alt="Class diagram", width=300, height=200]

Enabling the extension

Asciidoctor 0.1.4 does not yet allow extensions to be enabled via the command line. That is a feature coming in Asciidoctor 1.5.0. Until then, the easiest way to enable the extensions is to use a short wrapper script. The following script, asciidoctor-diagram, loads and registers the Asciidoctor Diagram extension, then invokes Asciidoctor in the same way as the asciidoctor command.

asciidoctor-diagram launch script
#!/usr/bin/env ruby

require 'asciidoctor' (1)
require 'asciidoctor/cli/options'
require 'asciidoctor/cli/invoker'

require 'asciidoctor-diagram' (2)

invoker = Asciidoctor::Cli::Invoker.new ARGV (3)
invoker.invoke!
exit invoker.code
1 Loads Asciidoctor
2 Loads and registers the Asciidoctor Diagram extensions
3 Invoke the Asciidoctor CLI

Put the asciidoctor-diagram script on your PATH, make it executable and use it in place of the asciidoctor command.

$ asciidoctor-diagram my-doc-with-cool-diagrams.adoc

After running the asciidoctor-diagram script on your document, go check out the cool diagrams it made for you!

Go play!

Now it’s time to go play with Asciidoctor Diagram. Explore what you can do with it and how it can be improved. To help you get started, check out these examples in the Asciidoctor Diagram repository. We look forward to hearing from you on the Asciidoctor discussion list or the Asciidoctor Diagram issue tracker.

Together, we can make diagrams and documentation come to life out of plain ol' text!


Introducing Asciidoctor.js live preview in your browser

by Guillaume Grossetie -

I’d like to introduce you to the easiest way to render any AsciiDoc file, local or remote, as HTML directly in your browser!

All you need to do is install the Chrome extension or the Firefox add-on. Then you can preview any AsciiDoc file as HTML just by visiting it!

How it works

The Chrome extension and the Firefox add-on use Asciidoctor.js to render AsciiDoc as HTML inside your browser. Both provide a toggle button to switch between HTML output and AsciiDoc source.

Here you can see a local AsciiDoc file rendered inside of Chrome.

chrome extension enabled
Chrome extension in action
You can view any AsciiDoc file on GitHub through the lens of Asciidoctor.js with this extension! Simply navigate to the file in the GitHub web interface (try this blog post) and click the Raw button that appears above the file preview. Looks much better, doesn’t it?

Future

Currently, we are using Asciidoctor.js based on Asciidoctor 0.1.2. We planned to cross-compile the newly-released Asciidoctor 0.1.4 to Javascript, to support the latest and greatest features!

We are also working on adding some cool new features :

  • browser-based editor using MarkItUp!

  • live reload to automatically refresh on local file changes

  • and many more…​

Contributing

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


Easier Documentation, Simpler Websites And Faster Collaboration @ OSCON 2013

by Dan Allen -

Do you find producing and collaborating on documentation or web content difficult? At OSCON 2013, we’ll work with you to reduce the friction of creating content by simplifying your content workflow, teaching you how to collaborate more efficiently and helping to make writing and publishing enjoyable!

OSCON banner

Join us on Tuesday, July 23 at our workshop titled Easier Documentation, Simpler Websites And Faster Collaboration to learn about tools and techniques that lighten your documentation workload and jumpstart your content strategy. To attend, register for OSCON 2013, then sign up for the workshop!

TIP: Use code ARQIKE for a 20% discount off registration!

How?

It begins with writing content…​

…​in the same format you use to write e-mail.

Plain text *embellished* with _subtle_ markup.

Indeed, that’s the focus of the lightweight markup language AsciiDoc. The AsciiDoc syntax feels natural and that keeps you focused on the content. Content written in AsciiDoc is easy to read and edit in raw form, which facilitates collaboration. It can also be translated into HTML for presentation, hello web publishing!

Zurb Foundation Yeti

Next, we do some baking.

After composing some documentation in AsciiDoc, we’ll pull together our content into a cohesive website using the static site generators Awestruct and Jekyll. Then we’ll leverage CSS frameworks like Bootstrap and Zurb Foundation to dress up the content with an elegant look and feel.

It’s push to publish!

We’ll then publish our website to GitHub Pages using a single command, git push.

That’s when the real fun starts. From GitHub, we can collaborate on the content using git and the web-based collaboration tools in the GitHub interface.

Revision history in GitHub
The revision history is safely tucked away in the git repository.

Don’t forget to chunk!

There are billions of devices connected to the web. And more are coming. Regardless of how the device market changes over time, the challenge for us remains the same. We need to get our content on all of them.

AsciiDoc is more than just a lightweight markup language. It enables and encourages us to write reusable, structured content.

Chunking Reusable content can be mixed and matched with other content to create a composition that suits a device, context or situation. It’s also a way to keep our content DRY (Don’t Repeat Yourself) so we don’t have to update the same content in a dozen places, or even two.

Structured content is meaningful, semantic content that is flagged using metadata. We can do lots of things with a document if we know what’s in it. We can pull out a lead or excerpt. We can hide content when it isn’t needed. We can present a structure and allow the user to drill into what they want to see.

Content no longer lives on a “page”. The future unit of publishing is the “chunk”. These smaller, discrete sources can be tuned to specific platforms or aggregated using automation.

The web is changing. It’s left the desktop. It’s now a road warrior. The way we think about content publishing must adapt. More than ever before, we must separate content from presentation.

Recap

Writing documentation is hard. So we don’t do it often enough. And yet, we’re skipping out on the best opportunity to reach and influence our target audience. Let’s do something about it.

  • lightweight markup makes writing documentation easier

  • static site generators and CSS frameworks make websites simpler

  • git and GitHub make collaborating on content and publishing it online faster

…​all powered by open source software:

Ruby

Git

AsciiDoc / Asciidoctor

Awestruct

Jekyll

Haml / Slim

SASS / Compass

Zurb Foundation

Travis CI

Let’s bake better documentation, together. Documentation that’s reusable and structured.

What, Where and When?

Title:

Easier Documentation, Simpler Websites And Faster Collaboration

Date:

Tuesday, July 23, 2013

Time:

1:30 - 5:00 PM (3h 30m)

Room:

D139/140, Oregon Convention Center

Type:

Workshop

Category:

Tools & Techniques

You can find all the details about the workshop, including the session abstract, on the official session page.

Who?

Attendees

Open source community members like you who are passionate about documentation and web publishing.

Not sure if that’s you? Do you contribute to, maintain or organize any of the following?

  • manuals, user guides, tutorials or READMEs

  • news, press releases or announcements

  • articles or books

  • brochures or press kits

  • conference or event information

  • request for proposals (RFPs)

  • resume or personal site

If you nodded, then you’re one of us :)

Trainers

Dan Allen Dan Allen

Dan is an open source advocate, community catalyst, author and speaker. He proudly pursues these passions as a Red Hat employee and community member.

In his role as Principal Software Engineer at Red Hat, he leads the Asciidoctor project and serves as the community manager for Arquillian. He draws on these experiences to help make a variety of open source projects wildly successful. Besides drinking a Trappist beer or indulging in Belgian chocolate, there’s nothing he’d rather do.

Sarah White Sarah White

Sarah is the content strategist for both the Arquillian and Asciidoctor projects—​an ideal position for someone passionate about open source, alien invasions and writing.

If there’s room for improvement, Sarah will find it. Lots of it.

Long ago, in a not-too-distant galaxy, she assessed hazardous waste sites and tracked pesticide routes through watersheds. So she knows a thing or two about identifying and eradicating stuff that kills, including software bugs and poor documentation.

Prerequisites

Knowledge of HTML and being comfortable using the commandline are both essential. Some knowledge of git and Ruby is useful, though a novice should be able to pick up the necessary training “on the job”.

Reading list

We’ve prepared some reading material that will give you a better idea of what the session is about and what you’ll be learning. These resources should also help you continue to learn about the subject after the workshop is over.

A full list of resources is available on the Reference Resources page on the workshop’s wiki.

We look forward to seeing you at OSCON!


Write Javadocs in AsciiDoc with Asciidoclet

by John Ericksen -

We’re excited to announce the newest member of the Asciidoctor family, Asciidoclet. Asciidoclet is a Javadoc Doclet based on Asciidoctor that enables developers to write Javadoc comments using the AsciiDoc syntax.

Motivation

From the very beginning, a concept the designers of Java got right was to include documentation with source code. This allowed documentation to stay closer in sync with ever-changing source and allowed multiple viewing platforms, most notably the HTML generation and IDE integration.

The main drawback of Javadoc has been the requirement to use embedded HTML fragments to achieve advanced (or even modest) formatting. This is where the AsciiDoc integration shines. Being a lightweight markup language, AsciiDoc gives developers access to advanced formatting without having to fiddle with low-level HTML markup. In other words, developers can focus on the content rather than the markup and still achieve a beautiful end result.

Pairing AsciiDoc with Javadocs means readable source and beautifully rendered Javadocs, the best of both worlds!

Usage

Once Asciidoclet is plugged into Javadoc, it’s just a matter of using AsciiDoc mark up in Javadocs. The following example demonstrates a number of features of Asciidoclet:

/**
 * = Asciidoclet (1)
 *
 * Sample comments that include +source code+. (2)
 *
 * [source,java] (3)
 * --
 * public class Asciidoclet extends Doclet {
 *     private final Asciidoctor asciidoctor = Asciidoctor.Factory.create();
 *
 *     @SuppressWarnings("UnusedDeclaration") (4)
 *     public static boolean start(RootDoc rootDoc) {
 *         new Asciidoclet().render(rootDoc);
 *         return Standard.start(rootDoc);
 *     }
 * }
 * --
 *
 * @author https://github.com/johncarl81[John Ericksen] (5)
 */
public class Asciidoclet extends Doclet {
}
1 Titles are easy to create using the = markup.
2 Paragraphs are the default and do not require the <p> html tag. Inline source may be marked up by surrounding the text in + symbols.
3 Source is easily marked up using the [source,language] tag and block delimiters, --, also called "fences"
4 The notorious @ symbol is automatically handled by Asciidoclet, avoiding the standard {@literal @} boilerplate.
5 Inline AsciiDoc markup is available within Javadoc tags. This example highlights link rendering.

Distribution

Asciidoclet is published to Maven Central. The artifact information is summarized in the table below.

Artifact information for Asciidoclet
Group Id Artifact Id Version Download

org.asciidoctor

asciidoclet

0.1.3*

pom jar javadoc (jar) source (jar)

* This release is based on the Asciidoctor 0.1.3 release.

Installation

Asciidoclet is a standard Javadoc Doclet and may be used as such. One of the easiest ways to install Asciidoclet is by adding it as a Doclet to the maven-javadoc-plugin:

Maven Doclet declaration
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <doclet>org.asciidoctor.Asciidoclet</doclet>
        <docletArtifact>
           <groupId>org.asciidoctor</groupId>
           <artifactId>asciidoclet</artifactId>
           <version>${asciidoclet.version}</version>
        </docletArtifact>
    </configuration>
</plugin>

We hope that this extension helps you push your Javadocs to new heights. As always, collaboration is welcome and you may find (and fork) the source on GitHub.

A big thanks to Alex Soto of the Asciidoctor Java integration project, Jason Porter and Dan Allen for their feedback and support and everyone else who contributes to the Asciidoctor project. Writing this extension could not have been easier because of the great work and collaboration of the Asciidoctor community.


asciidoctor.js - Render AsciiDoc in your browser!

by Dan Allen -

We’ve combined Asciidoctor and Opal to bring AsciiDoc rendering to the browser!

Introduction

Opal

asciidoctor.js uses the Opal Ruby-to-JavaScript cross compiler to generate a direct JavaScript port of Asciidoctor, an implementation of AsciiDoc. The result is AsciiDoc rendering in the browser!

The project consists primarily of a Rake build script that executes the Opal compiler on the Asciidoctor source code to produce the asciidoctor.js script.

Opal parses the Ruby code and any required libraries, then rewrites the code into JavaScript under the Opal namespace. The resulting JavaScript can be executed in any JavaScript runtime environment, such as a browser or node.js application.

Proving the concept

When I first discovered Opal, I thought to myself, "yeah, this could work." Little did I know that achieving this proof of concept was more than a small task.

The effort involved filling gaps in Opal to support all the features of the Ruby standard library that Asciidoctor uses, as well as changes in Asciidoctor to make it compatible with constraints imposed by JavaScript (such as immutable strings).

While there are still some shortcomings, I’m proud to say that asciidoctor.js can successfully render the complete AsciiDoc User Guide (a document that has served as a compliance benchmark throughout the development of Asciidoctor).

The scripts

There are two scripts generated by the Rake build that are needed to run Asciidoctor in the browser:

opal.js

The Ruby runtime in JavaScript

asciidoctor.js

The JavaScript port of Asciidoctor

Don’t fret over the large size of these files. We haven’t even started to optimize, having only just achieved the proof of concept.

With that said, both files gzip rather nicely, bringing asciidoctor.js down from over 500K to around 90K. There are options in Opal to generate more efficient code, but they are causing problems at the moment. Once we sort out those issues, the size of the generated files should become quite acceptable.

You need to load both files into your JavaScript environment to use Asciidoctor. For instance, in an HTML page, add these two <script> tags (ideally at the bottom of the page):

<script src="opal.js"></script>
<script src="asciidoctor.js"></script>

You can see these scripts in action by running the examples, described in the README.

Usage

To interact with the generated code, you either:

  1. Write code in Ruby that hooks into the native JavaScript environment, which Opal compiles into JavaScript

  2. Invoke the JavaScript APIs that Opal generates directly from JavaScript

Here’s an example that shows how Ruby can interact with the native JavaScript environment to render a string of AsciiDoc in the browser:

data = %(= asciidoctor.js - Render AsciiDoc in your browser!
Dan Allen
2013-05-21

We've combined http://asciidoctor.org[Asciidoctor] and
http://opalrb.org[Opal] to bring AsciiDoc rendering to the browser!)

$window.addEventListener 'DOMContentLoaded', proc {
  html_doc = Asciidoctor.render(data, :safe => :safe,
    :attributes => %w(notitle! anchors imagesdir=./images))
  $document.getElementById('content').innerHTML = html_doc
}, false

Changes to Asciidoctor

At the moment, some changes are necessary in Asciidoctor to get it to compile with Opal. These changes are maintained in the asciidoctor.js branch of the Asciidoctor git repository, from which asciidoctor.js is compiled. The goal is to eventually eliminate all of these differences so that Asciidoctor can be compiled to JavaScript as is.

Go play!

Now it’s time to go play with asciidoctor.js. Explore what you can do with it and how it can be improved. Then, get involved in either Asciidoctor or Opal to help make AsciiDoc in the browser the best it can be!


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.


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!


  • 1 of 2