A quick tour

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

Your first conversion

Import the convert function directly from @asciidoctor/core — no instantiation needed:

import { convert } from '@asciidoctor/core'

const html = await 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:

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

To convert a file, use convertFile:

import { convertFile } from '@asciidoctor/core'

await convertFile('/path/to/file.adoc') (1)

1	Writes the output to `file.html` in the same directory.

To capture the HTML output in a variable instead of writing it to a file:

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

Load and convert

Use loadFile to parse an AsciiDoc file into a Document object:

import { loadFile } from '@asciidoctor/core'

const doc = await loadFile('file.adoc')
console.log(doc.getDocumentTitle())
console.log(doc.getAttributes())

To convert the loaded document:

const doc = await loadFile('file.adoc')
const html = await doc.convert()

Use load to parse an AsciiDoc string directly:

import { load } from '@asciidoctor/core'

const doc = await load('Hello, _Asciidoctor_')
const html = await doc.convert()

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

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/data/asciidoctor-default.css

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

import { convertFile } from '@asciidoctor/core'

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

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

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

What’s next?

Now that you know the basics, explore the Convert options to learn how to customize the conversion.