asciidoctor.js - Render AsciiDoc in your browser!
by -
We’ve combined Asciidoctor and Opal to bring AsciiDoc rendering to the browser!
Introduction
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:
-
Write code in Ruby that hooks into the native JavaScript environment, which Opal compiles into JavaScript
-
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
}, falseChanges 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.