asciidoctor

Asciidoctor.js: AsciiDoc in JavaScript powered by Asciidoctor

This package is a convenience wrapper that bundles @asciidoctor/core and the Asciidoctor CLI. It provides a native JavaScript implementation of Asciidoctor with no compilation step.

The API is asynchronous: all parsing and conversion operations return a Promise.

Requirements

Node.js >= 24

Install

$ npm i asciidoctor --save

Usage

Convert a string

sample.js

import asciidoctor from 'asciidoctor'

const content = 'https://asciidoctor.org[*Asciidoctor*] running on Node.js!'
const html = await asciidoctor.convert(content) // ①
console.log(html) // ②

1. Convert AsciiDoc content to HTML5 — the call returns a Promise and must be awaited
2. Print the HTML5 output to the console

Save the file as sample.js and run it using the node command:

$ node sample.js

You should see the following output in your terminal:

<div class="paragraph">
<p><a href="https://asciidoctor.org"><strong>Asciidoctor</strong></a> running on Node.js!</p>
</div>

Convert a file

convert-file.js

import { convertFile } from 'asciidoctor'

await convertFile('document.adoc', { safe: 'safe' })

Load without converting

Use load when you need to inspect the parsed document model before (or instead of) converting:

load.js

import { load } from 'asciidoctor'

const doc = await load('== Hello, World!\n\nThis is Asciidoctor.')
console.log(doc.getTitle())    // Hello, World!
console.log(doc.getBlocks())   // array of top-level blocks
const html = await doc.convert()
console.log(html)

CLI

The asciidoctor command is available after installation:

$ asciidoctor document.adoc

Common options:

$ asciidoctor -b html5 -a toc document.adoc
$ asciidoctor -o - document.adoc          # output to stdout
$ asciidoctor --help                       # show all options
$ asciidoctor --help syntax                # show AsciiDoc syntax reference

Contributing

In the spirit of free software, everyone is encouraged to help improve this project. If you discover errors or omissions in the source code, documentation, or website content, please don’t hesitate to submit an issue or open a pull request with a fix. New contributors are always welcome!

The Contributing guide provides information on how to contribute.

If you want to write code, the Contributing Code guide will help you to get started quickly.

Changelog

Refer to the CHANGELOG for a complete list of changes.

Copyright

Copyright (C) 2013-present Dan Allen, Guillaume Grossetie, Anthonny Quérouil and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License.

See the LICENSE file for details.