# asciidoctor

> A JavaScript AsciiDoc processor powered by Asciidoctor

Latest version **4.1.0** (published 2026-09-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install asciidoctor
pnpm add asciidoctor
yarn add asciidoctor
bun add asciidoctor
```

Provides the commands `asciidoctor`, `asciidoctorjs`.

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.1.0 |
| Published | 2026-09-22 |
| First published | 2019-03-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 1 |
| Unpacked size | 330.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 804 |
| Maintainers | ggrossetie |
| Keywords | asciidoc, asciidoctor, javascript, library |

## Links

- npm: https://www.npmjs.com/package/asciidoctor
- Repository: https://github.com/asciidoctor/asciidoctor.js
- Issues: https://github.com/asciidoctor/asciidoctor.js/issues
- npm.io page: https://npm.io/package/asciidoctor

## Dependencies (1)

- [@asciidoctor/core](https://npm.io/package/@asciidoctor/core.md) 4.1.0

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 4.1.0 (latest) — 2026-09-22
- 4.0.0-alpha.6 (testing) — 2026-06-03
- 2.2.9 (latest-2) — 2026-04-29
- 4.0.11 — 2026-08-18
- 4.0.10 — 2026-08-17
- 4.0.9 — 2026-08-16
- 4.0.8 — 2026-08-06
- 4.0.7 — 2026-07-31
- 4.0.6 — 2026-07-26
- 4.0.5 — 2026-07-21
- 4.0.4 — 2026-07-15
- 4.0.3 — 2026-07-13
- 4.0.2 — 2026-07-06
- 4.0.1 — 2026-07-01
- 4.0.0 — 2026-06-22
- … 39 more at https://npm.io/package/asciidoctor/versions

## README

# 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.

---
_Source: https://npm.io/package/asciidoctor · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._