= 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)

// 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 [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)

// 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 http://opensource.org/licenses/MIT/[MIT License]. For the full text of the license, see the link:LICENSE[LICENSE] file.