README.md
1# Asciidoctor.js: AsciiDoc in JavaScript powered by Asciidoctor
2
3Asciidoctor.js brings AsciiDoc to the JavaScript world!
4
5This project uses [Opal](https://opalrb.com/) to transpile [Asciidoctor](http://asciidoctor.org), a modern implementation of AsciiDoc, from Ruby to JavaScript to produce _asciidoctor.js_.
6The _asciidoctor.js_ script can be run on any JavaScript platform, including Node.js, GraalVM and, of course, a web browser.
7
8## Install
9
10```console
11$ npm i asciidoctor --save
12```
13
14## Usage
15
16Here is a simple example that converts AsciiDoc to HTML5:
17
18**sample.js**
19
20```javascript
21import asciidoctor from 'asciidoctor'
22
23const Asciidoctor = asciidoctor() // ①
24const content = 'http://asciidoctor.org[*Asciidoctor*] ' +
25 'running on https://opalrb.com[_Opal_] ' +
26 'brings AsciiDoc to Node.js!'
27const html = Asciidoctor.convert(content) // ②
28console.log(html) // ③
29```
301. Instantiate the Asciidoctor.js library
312. Convert AsciiDoc content to HTML5 using Asciidoctor.js
323. Print the HTML5 output to the console
33
34Save the file as _sample.js_ and run it using the `node` command:
35
36```console
37$ node sample.js
38```
39
40You should see the following output in your terminal:
41
42```html
43<div class="paragraph">
44<p><a href="http://asciidoctor.org"><strong>Asciidoctor</strong></a> running on <a href="http://opalrb.com"><em>Opal</em></a> brings AsciiDoc to Node.js!</p>
45</div>
46```
47
48If you want to know more about Asciidoctor.js, please read the [User Manual](https://docs.asciidoctor.org/asciidoctor.js/latest/).
49
50## Contributing
51
52In the spirit of [free software](https://www.gnu.org/philosophy/free-sw.html), _everyone_ is encouraged to help improve this project.
53If 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.
54New contributors are always welcome!
55
56The [Contributing](https://github.com/asciidoctor/asciidoctor.js/blob/main/CONTRIBUTING.adoc) guide provides information on how to contribute.
57
58If 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.
59
60## Copyright
61
62Copyright (C) 2013-present Dan Allen, Guillaume Grossetie, Anthonny Quérouil and the Asciidoctor Project.
63Free use of this software is granted under the terms of the MIT License.
64
65See the [LICENSE](https://github.com/asciidoctor/asciidoctor.js/blob/main/LICENSE) file for details.
66