README
= Asciidoctor Highlight.js :npm-name: asciidoctor-highlight.js :gh-name: jirutka/{npm-name}
ifdef::env-github[] image:https://github.com/{gh-name}/workflows/CI/badge.svg[CI Status, link=https://github.com/{gh-name}/actions?query=workflow%3A%22CI%22] image:https://img.shields.io/npm/v/{npm-name}.svg?style=flat[npm Version, link="https://www.npmjs.org/package/{npm-name}"] endif::env-github[]
This project provides an https://asciidoctor.org/docs/asciidoctor.js[Asciidoctor.js] extension for highlighting source listing blocks using https://highlightjs.org[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 http://asciidoctor.org/docs/user-manual/#callouts[callouts], http://asciidoctor.org/docs/user-manual/#passthroughs[passthroughs] inside a code and all other substitutions, except highlighting of specified lines (attribute highlight
).
== Requirements
- https://nodejs.org/[Node.js] >=8.10 footnote:[Node versions older than 12.0.0 are not tested since 0.4.0.]
- https://www.npmjs.com/package/@asciidoctor/core[@asciidoctor/core] >=2.0.0 <2.3.0
- https://www.npmjs.com/package/highlight.js[highlight.js] >=10.7.0 <12.0.0
== Installation
Install {npm-name} from npmjs.com:
[source, sh, subs="+attributes"] npm install --save {npm-name}
== 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 [source, js, subs="+attributes"]
// Load asciidoctor.js and {npm-name}. const asciidoctor = require('@asciidoctor/core')() const highlightJsExt = require('{npm-name}')
// Register the extension into global registry. highlightJsExt.register(asciidoctor.Extensions)
[source, js] console.log('Hello, world!')
`
const html = asciidoctor.convert(content, {
attributes: { 'source-highlighter': 'highlightjs-ext' },
})
console.log(html)
// Convert the content to HTML.
const content = .Using custom extensions registry [source, js, subs="+attributes"]
// Load asciidoctor.js and {npm-name}. const asciidoctor = require('@asciidoctor/core')() const highlightJsExt = require('{npm-name}')
// Register the extension into custom registry. const registry = asciidoctor.Extensions.create() highlightJsExt.register(registry)
[source, js] console.log('Hello, world!')
`
const html = asciidoctor.convert(content, {
'extension_registry': registry,
attributes: { 'source-highlighter': 'highlightjs-ext' },
})
console.log(html)
// Convert the content to HTML.
const content = === 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 http://opensource.org/licenses/MIT/[MIT License]. For the full text of the license, see the link:LICENSE[LICENSE] file.