A quick tour

Asciidoctor.js is a fast text processor for converting AsciiDoc content to HTML5, slidedecks and other formats. This is quick tour will give you an overview of how to convert AsciiDoc content to HTML5.

Your first conversion

The first thing you need to do is instantiate Asciidoctor.js to get a processor:

var asciidoctor = Asciidoctor()

To convert an AsciiDoc-formatted string:

var html = asciidoctor.convert('Hello, _Asciidoctor_')
console.log(html)
// <div class="paragraph">
// <p>Hello, <em>Asciidoctor</em></p>
// </div>

When converting a string, the header and footer are excluded by default to make Asciidoctor consistent with other lightweight markup engines like Markdown. If you want to produce a standalone document, enable it using the standalone option:

var html = asciidoctor.convert('*This* is Asciidoctor.', { standalone: true })

Alternatively, you can use the function convertFile to convert a file containing AsciiDoc markup to HTML 5:

var doc = asciidoctor.convertFile('/path/to/file.adoc') (1)

1	The command will output to the file `file.html` in the same directory. The variable `doc` will contain an Asciidoctor.Document object.

Alternatively, you can capture the HTML 5 output in a variable instead of writing it to a file:

var html = asciidoctor.convertFile('/path/to/file.adoc', { to_file: false, standalone: true })

As seen above, the convert functions accept an optional argument to specify options.
Use of this argument is described in the Convert options section.

If you are using Node.js, you can also use a Buffer:

var html = asciidoctor.convert(fs.readFileSync('/path/to/file.adoc')) (1)

1	`readFileSync` will return a `Buffer`: nodejs.org/api/fs.html#fs_fs_readfilesync_path_options

Load and convert

To parse an AsciiDoc file into an Asciidoctor.Document object:

var doc = asciidoctor.loadFile('file.adoc')

You can get information about the document:

console.log(doc.getDocumentTitle())
console.log(doc.getAttributes())

More than likely, you will want to convert the document. To convert an Asciidoctor.Document to HTML5, use the convert function on a Document:

var doc = asciidoctor.loadFile('file.adoc')
doc.convert()

As with the convert functions, it’s also possible to load an AsciiDoc-formatted string and a Buffer:

var doc = asciidoctor.load('Hello, _Asciidoctor_')

var doc = asciidoctor.load(fs.readFileSync('/path/to/file.adoc'))

Styling the HTML with CSS

Asciidoctor.js uses CSS for HTML document styling. It comes bundled with a stylesheet, named asciidoctor.css.

The default stylesheet is located at node_modules/@asciidoctor/core/dist/css/asciidoctor.css

When you generate a document using Node.js, the asciidoctor.css stylesheet is embedded into the HTML output by default (when the safe mode is less than secure).

asciidoctor.convertFile('/path/to/file.adoc', { safe: 'safe' })

To have your document link to the stylesheet, set the linkcss attribute:

asciidoctor.convertFile('/path/to/file.adoc', { safe: 'safe', attributes: { linkcss: true } })