# 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

```console
$ npm i asciidoctor --save
```

## Usage

### Convert a string

**sample.js**

```javascript
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:

```console
$ node sample.js
```

You should see the following output in your terminal:

```html
<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**

```javascript
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**

```javascript
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:

```console
$ asciidoctor document.adoc
```

Common options:

```console
$ 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](https://www.gnu.org/philosophy/free-sw.html), _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](https://github.com/asciidoctor/asciidoctor.js/blob/main/CONTRIBUTING.adoc) guide provides information on how to contribute.

If you want to write code, the [Contributing Code](https://github.com/asciidoctor/asciidoctor.js/blob/main/CONTRIBUTING-CODE.adoc) guide will help you to get started quickly.

## Changelog

Refer to the [CHANGELOG](https://github.com/asciidoctor/asciidoctor.js/blob/main/CHANGELOG.adoc) 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](https://github.com/asciidoctor/asciidoctor.js/blob/main/LICENSE) file for details.