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

Change the theme

The theme controls the colors that are used for the tokens (keywords, strings, methods, etc.) in the highlighted code. By default, highlight.js is configured to use the github theme. You can change the theme used by highlight.js by setting the highlightjs-theme attribute.

:source-highlighter: highlight.js
:highlightjs-theme: monokai

The theme is loaded from the CDN, so any theme supported by the version of highlight.js that Asciidoctor uses is supported. Refer to cdnjs.com/libraries/highlight.js/9.18.3 for a list of themes (filter by Asset Type: Styling). The value of the highlightjs-theme attribute is the basename of the file minus the .min.css file extension.

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.