Highlight.js

Highlight.js is a popular client-side syntax highlighter that supports a broad range of languages.

Activate highlight.js

To activate highlight.js, add the following attribute entry to the header of your AsciiDoc file:

:source-highlighter: highlight.js

By default, Asciidoctor will link to the highlight.js library and stylesheet hosted on cdnjs. The version of the highlight.js library Asciidoctor loads from the CDN only includes support for languages in the common language bundle (apache, bash, coffeescript, cpp, cs, css, diff, http, ini, java, javascript, json, makefile, markdown, nginx, objectivec, perl, php, properties, python, ruby, shell, sql, xml, and yaml).

Load support for additional languages

To load additional languages supported by highlight.js, list them in the value of the highlightjs-languages document attribute. Separate each language by a comma followed by an optional space.

The common highlight.js bundle does not include support for Rust and Swift. Let’s set the highlightjs-languages attribute so the HTML converter loads support for them into the HTML page.

:source-highlighter: highlight.js
:highlightjs-languages: rust, swift

The highlightjs-languages attribute only applies when generating a standalone HTML document (i.e., backend: html, standalone: true). It does not work when generating embedded HTML, which is used by site generator integrations such as Antora.

Use a custom highlight.js library

If you’d rather use a personal copy of highlight.js instead of the one hosted on the CDN, follow these steps:

  1. Create your custom bundle on the download page.

  2. Download and unpack the zip into a folder called highlight adjacent to your AsciiDoc file (or in the output directory, if different)

  3. Rename highlight/highlight.pack.js to highlight/highlight.min.js

  4. Rename highlight/styles/github.css to highlight/styles/github.min.css

    • Replace github with the name of the highlightjs-theme you are using, if different.

  5. Add the attribute entry :highlightjsdir: highlight to the header of your AsciiDoc file.

    • Alternatively, you can pass the -a highlightjsdir=highlight flag when invoking the Asciidoctor CLI.

The output file will use your personal copy of the highlight.js library and stylesheet instead of the one hosted on cdnjs.