This documentation covers a prerelease version of the software. Follow this link to view the documentation for the stable version (3.0) instead.

Install guide

On this page, you’ll learn:

  • How to install Asciidoctor.js.

  • How to set up 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/core
If you prefer Yarn over npm, you can install Asciidoctor.js using yarn add @asciidoctor/core

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.

<script type="module">
  import { convert } from './node_modules/@asciidoctor/core/build/browser/index.js'
</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

import { convert } from '@asciidoctor/core'

@asciidoctor/core is also available as a CommonJS (CJS) module:

const { convert } = require('@asciidoctor/core')

What’s next?

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