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 attributesource-language
. It can be any language name or alias supported by highlight.js,none
to skip highlighting, orauto
to use highlight.js’s auto-detection. The default isnone
.
License
This project is licensed under MIT License. For the full text of the license, see the LICENSE file.
- Node versions older than 12.0.0 are not tested since 0.4.0.