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!

  • 1 of 1