Install guide

On this page, you’ll learn:

How to install Asciidoctor.js.
How to setup Asciidoctor.js in your JavaScript environment.

Install Asciidoctor.js

We recommend using the latest long term support (LTS) release of Node. While you can use other versions of Node, Asciidoctor.js is only tested against active LTS releases.

Once you’ve installed an active Node LTS release on your machine, open a terminal and type:

$ npm i asciidoctor

If you prefer Yarn over npm, you can install Asciidoctor.js using yarn add asciidoctor

Asciidoctor.js provides different builds for different JavaScript environments. See below for a link to the right one and instructions on how to use it.

Basic browser setup

Import Asciidoctor.js in a <script type="module"> tag. You can instantiate the processor using the Asciidoctor().

<script type="module">
  import Asciidoctor from './node_modules/@asciidoctor/core/dist/browser/asciidoctor.js'
  const asciidoctor = Asciidoctor()
</script>

You need to pay attention to local testing — if you try to load the HTML file locally (i.e. with a file:// URL), you’ll run into CORS errors due to JavaScript module security requirements. You need to do your testing through a server.

Learn more about JavaScript modules.

Node

const Asciidoctor = require('asciidoctor')

const asciidoctor = Asciidoctor()

AMD (System.js, RequireJS, etc)

requirejs(['asciidoctor'], function (asciidoctor) {
  //...
})

TypeScript

import Processor from 'asciidoctor'

const processor = Processor()

We are using the name processor to avoid confusion with the Asciidoctor namespace.

Webpack

import Asciidoctor from 'asciidoctor'

const asciidoctor = Asciidoctor()

GraalVM

Node.js application

GraalVM can run Node.js applications.
To install asciidoctor.js module, use the npm executable in the /bin folder of the GraalVM package.

Create the following code snippet to a file named app.js and save it in the same directory where you installed the Node.js modules:

app.js

const Asciidoctor = require('asciidoctor')

const asciidoctor = Asciidoctor()

Then execute it on GraalVM using the node command (available in the /bin folder of the GraalVM package):

$ node app.js

Embed in a JVM-based application

With the Graal Polyglot API, you can embed JavaScript code in a JVM-based application. However, this is currently an experimental feature. Please, share any feedback or issues you may have.

The Graal Polyglot feature gives you a "pure" JavaScript (ECMAScript) engine, not a Node.js engine. In other words, Node.js features such as require or core module such as fs won’t be available.

To embed Asciidoctor.js in a Java application, create the following code snippet to a file named app.js (tested on v21.1.0):

app.js

var asciidoctor = Asciidoctor()

Copy the file node_modules/asciidoctor.js/dist/graalvm/asciidoctor.js in the resources of your application. Then create a Java file named AsciidoctorGraalVM.java with the following content:

AsciidoctorGraalVM.java

import org.graalvm.polyglot.Context;

import java.io.File;
import java.io.IOException;
import java.net.URISyntaxException;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;

public class AsciidoctorGraalVM {

  public static void main(String... args) {
    Context context = Context.newBuilder("js")
                                .allowIO(true)
                                .allowAllAccess(true)
                                .allowPolyglotAccess(PolyglotAccess.ALL)
                                .build();
    context.getPolyglotBindings().putMember("IncludeResolver", new IncludeResolver()); (1)
    context.eval("js", "var IncludeResolver = Polyglot.import('IncludeResolver');");
    ClassLoader classLoader = AsciidoctorGraalVM.class.getClassLoader();
    context.eval("js", "load('" + classLoader.getResource("asciidoctor.js") + "')"); (2)
    context.eval("js", "load('" + classLoader.getResource("app.js") +"')"); (2)
  }

  public static class IncludeResolver {
    public String read(String path) throws IOException, URISyntaxException {
      Path filePath = Paths.get(path);
      List<String> lines;
      File file = filePath.toFile();
      if (file.exists()) {
        lines = Files.readAllLines(filePath, StandardCharsets.UTF_8);
      } else {
        Path fileName = filePath.getFileName();
        URL url = this.getClass().getClassLoader().getResource(fileName.toString());
        if (url != null) {
          lines = Files.readAllLines(Paths.get(url.toURI()), StandardCharsets.UTF_8);
        } else {
          lines = new ArrayList<>();
        }
      }
      return String.join("\n", lines);
    }

    public String pwd() {
      return Paths.get("").toAbsolutePath().toString();
    }
  }
}

1	The `IncludeResolver` class will be used to read the content of a file when using the `include::` directive
2	Make sure that `asciidoctor.js` and `app.js` are available in the classpath of the application

The source attribute of the global load method provided by GraalVM can be of type:

a String: the path of the source file or a URL to execute.
java.lang.URL: the URL is queried for the source code to execute.
java.io.File: the File is read for the source code to execute.

What’s next?

Now that Asciidoctor.js is installed, you are ready to take a quick tour.