Asciidoctor Highlight.js

This project provides an Asciidoctor.js extension for highlighting source listing blocks using highlight.js right during document conversion (instead of in browser on client-side as the built-in highlight.js support).

It supports all Asciidoctor features such as callouts, passthroughs inside a code and all other substitutions, except highlighting of specified lines (attribute highlight).

Requirements

• Node.js >=8.10 ^[1]

• @asciidoctor/core >=2.0.0 <2.3.0

• highlight.js >=10.7.0 <12.0.0

Installation

Install asciidoctor-highlight.js from npmjs.com:

npm install --save asciidoctor-highlight.js

Usage

Assign highlightjs-ext to the source-highlighter attribute in your document’s header or via Asciidoctor.js parameters.

Node.js

Using global extensions registry

// Load asciidoctor.js and asciidoctor-highlight.js.
const asciidoctor = require('@asciidoctor/core')()
const highlightJsExt = require('asciidoctor-highlight.js')

// Register the extension into global registry.
highlightJsExt.register(asciidoctor.Extensions)

// Convert the content to HTML.
const content = `
[source, js]
console.log('Hello, world!')
`
const html = asciidoctor.convert(content, {
  attributes: { 'source-highlighter': 'highlightjs-ext' },
})
console.log(html)

Using custom extensions registry

// Load asciidoctor.js and asciidoctor-highlight.js.
const asciidoctor = require('@asciidoctor/core')()
const highlightJsExt = require('asciidoctor-highlight.js')

// Register the extension into custom registry.
const registry = asciidoctor.Extensions.create()
highlightJsExt.register(registry)

// Convert the content to HTML.
const content = `
[source, js]
console.log('Hello, world!')
`
const html = asciidoctor.convert(content, {
  'extension_registry': registry,
  attributes: { 'source-highlighter': 'highlightjs-ext' },
})
console.log(html)

Attributes

You can further customize the source block output with additional highlight.js attributes:

highlightjs-default-lang

Controls the default source code language for fallback when the language is not specified in a source block or with attribute source-language. It can be any language name or alias supported by highlight.js, none to skip highlighting, or auto to use highlight.js’s auto-detection. The default is none.

License

This project is licensed under MIT License. For the full text of the license, see the LICENSE file.

---

1. Node versions older than 12.0.0 are not tested since 0.4.0.