Starting the AsciiDoc Specification Journey

by Sarah White and Dan Allen -

After numerous calls for an AsciiDoc specification over the past year, it’s abundantly clear the community is ready for AsciiDoc to take this step. We agree. We also reached out to Stuart, the originator of AsciiDoc, and we have his support as well. So now’s the perfect time to pursue it.

A new home at the Eclipse Foundation

We want AsciiDoc to have a strong future and the resources it needs to evolve and grow. To achieve this, we’ve decided to submit a proposal for an AsciiDoc language specification to the Eclipse Foundation. The Eclipse Foundation provides a home for developing specifications and is committed to transparency and open source, values that align well with AsciiDoc and its community. The Eclipse Foundation Specification Process (EFSP) provides a clear, yet customizable structure that reduces the risk of the process stalling and ensures the outcome will be usable in the real world. The process is public, vendor neutral, and all source materials and final artifacts are open source.

What will it mean for AsciiDoc to become a specification?

The specification for the AsciiDoc language will include an open source specification document, which defines required and optional API definitions, semantic behaviors, data formats, and protocols, as well as an open source Technology Compatibility Kit (TCK) that developers can use to develop and test compatible implementations. (Those of you who know Dan and I from before Asciidoctor know that an open source TCK is a hard requirement for us). A compatible implementation, as defined by the EFSP, must fully implement all non-optional elements of a specification version, must fulfill all the requirements of the corresponding TCK, and must not alter the specified API.

For users and developers alike, the AsciiDoc specification will mean a clear, working definition of what AsciiDoc is and how it should be interpreted. Developers will be able to build implementations, tools, and services around AsciiDoc without risk of diluting its meaning or splintering it. In turn, users will have more options, greater document portability, and the assurance that compatible implementations and tools will handle their AsciiDoc documents according to a versioned specification.

What will happen to Asciidoctor?

We plan to make Asciidoctor (the RubyGem) an independent, compatible implementation of AsciiDoc (the specification). (That doesn’t mean Asciidoctor as a whole is moving to the Eclipse Foundation). This may mean adding, removing, or changing features in Asciidoctor to meet the specification’s required and optional elements in order to pass the TCK. The Asciidoctor.js and AsciidoctorJ projects, if they choose, may also decide to become independent, compatible implementations with far greater freedom than before. And it will give space for emerging implementations to bring AsciiDoc to even more platforms.

We’ll know more—​and keep you updated on what to expect—​once the specification process gets under way.

Ready? Set. Spec!

The next step in creating the AsciiDoc specification is to propose it as a specification project to the Eclipse Foundation. The proposal, which Dan and I (as OpenDevise, on behalf of Asciidoctor) plan to submit, will be reviewed by the Eclipse Management Organization, then posted for community review and comment. To learn more about the specification process, I encourage you to check out Wayne Beaton’s posts Part II: The EFSP and Part III: Creation. The specification process is a fork of the Eclipse Development Process, which you can read about in Part I: The EDP. You can also read the EFSP documentation.

With a specification process that can be adapted to suit the needs of the AsciiDoc community, Dan and I believe the language will evolve in a sustainable and substantive manner that keeps pace with the community’s needs, now and into the future. We’re really excited to get started, and we hope you’ll join us on this journey to make AsciiDoc a specification!

Making the switch to Semantic Versioning

by Dan Allen -

After years of talking about it, we’re finally ready to make the switch to Semantic Versioning in Asciidoctor. This switch will happen as part of the next major release for each participating project.

About Semantic Versioning

Semantic Versioning (or SemVer, for short) is a logical system for selecting version numbers based on a simple MAJOR.MINOR.PATCH sequence.

  • A MAJOR version is for introducing incompatible changes (large or small).

  • A MINOR version is for adding backward-compatible functionality.

  • A PATCH version is for making bug fixes (backward compatible, of course).

There’s also room for a prerelease version via build metadata. You can learn more at https://semver.org.

In our current system, patch releases are indistinguishable from major and minor releases and there’s only a single release line. Experience has taught us (the hard way) that this situation is neither clear or sustainable. For us, SemVer is about having better communication and room to grow. It’s a system based on shared expectations and trust. Although it may not be perfect, SemVer should help to understand what a version number entails and when to upgrade. We can’t expect it to prevent breaking something, but at least you’ll know when it might.

Versioning projects independently

Switching to SemVer also means that the Asciidoctor projects, namely Asciidoctor, AsciidoctorJ, and Asciidoctor.js, will be versioned independently. Other projects in the ecosystem will likely start versioning independently as well (in fact, some already have).

AsciidoctorJ and Asciidoctor.js have both reached a point where the projects are much more than a redistribution of the Asciidoctor RubyGem. They have their own API, extensions model, custom features, and platform integration. And that warrants having their own version line. An independent version line will also allow users to better understand what to expect in each release.

After speaking with Robert (AsciidoctorJ lead) and Guillaume (Asciidoctor.js lead), here’s the system we agreed on:

  • The core processors (Asciidoctor, AsciidoctorJ, and Asciidoctor.js) will move to SemVer starting with the 2.0.0 release. We plan for all three projects to make this major version shift at roughly the same time to minimize confusion.

  • If Asciidoctor.js or AsciidoctorJ need a change in Asciidoctor, they can force Asciidoctor to be released. This means Asciidoctor will need to be “release ready” at all times. A patch or minor release won’t need much discussion, but a major release will, of course.

  • We will not attempt to align the version numbers between the three projects after 2.0.0. Guillaume laid out a strong case that trying to align the version numbers would work against SemVer and thus result in the version numbers losing their meaning. This does introduce the complexity of having to document the version of Asciidoctor that Asciidoctor.js or AsciidoctorJ provides. However, both AsciidoctorJ and Asciidoctor.js provide an API for accessing the version of the underlying Asciidoctor release. The release number is also available via the asciidoctor-version document attribute.

We considered ways to lock Asciidoctor, AsciidoctorJ, and Asciidoctor.js to the same version while still adhering to SemVer. However, we reached the conclusion that doing that would only perpetuate the situation that’s caused the backup of releases we’ve seen. It’s best if the projects have the freedom to release when the time is right to release. And with three version number segments (MAJOR.MINOR.PATCH), we finally have enough space for those releases to happen!

Next steps

We’ll start by repackaging the Asciidoctor 1.5.8 release as 2.0.0, with some minor adjustments to drop unsupported versions of Ruby. AsciidoctorJ and Asciidoctor.js will then follow with their 2.0.0 releases. At that point, we’ll stick to versioning according to SemVer rules as outlined above.

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.

UPDATE: We have migrated the funding platform for the Asciidoctor project from BountySource to OpenCollective. If you wish to provide financial support for the Asciidoctor project, please visit Asciidoctor on OpenCollective.

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.

Attend Easier Documentation, Simpler Websites And Faster Collaboration to learn how:

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

Strategy
Tech

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
https://opalrb.com[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.

  • 1 of 2