[[asciidoctor-js]]
= Asciidoctor.js: AsciiDoc in your _browser_
Dan Allen <https://github.com/mojavelinux[@mojavelinux]>
v1.0, 2013-05-21
:username: mojavelinux

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

== Introduction

https://github.com/asciidoctor/asciidoctor.js[Asciidoctor.js] uses the http://opalrb.org[Opal] Ruby-to-JavaScript cross compiler to generate a direct JavaScript port of http://asciidoctor.org[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, ``Sure, 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:

[itemized%brief]
opal.js:: The Ruby runtime in JavaScript
asciidoctor.js:: The JavaScript port of Asciidoctor

[WARNING]
====
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 under 100K.
As we learn to optimize Opal, 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):

[source,html]
----
<script src="opal.js"></script>
<script src="asciidoctor.js"></script>
----

You can see these scripts in action by running the examples, described in the https://github.com/asciidoctor/asciidoctor.js#readme[README].

== Usage

To interact with the generated code, you either:

[loweralpha]
. 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:

[source,ruby]
----
content = %(= Asciidoctor.js: 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(content, :safe => :safe,
    :attributes => %w(notitle! anchors imagesdir=./images))
  $document.getElementById('content').innerHTML = html_doc
}, false
----

== Changes to Asciidoctor

Some changes were necessary in Asciidoctor to get it to compile with Opal.
These changes have been merged into the upstream and will be part of the Asciidoctor 1.5.0 release.

== 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!