antora-highlightjs-extension

Antora Highlight.js Extension

Highlight.js is a syntax highlighting library that dynamically highlights code snippets in web pages. It supports a wide range of programming languages and is easy to integrate into Antora projects. By using Highlight.js in an Antora project, developers can enhance the readability and visual appeal of code examples, making it easier for users to understand and follow along with the documentation

Features

This extension wants to make it easier to use Highlight.js in Antora projects. It offers the following features:

• Autodetect used languages: Configures the highlight.js languages based on the used source blocks that are defined in the asciidoc files.
• Show unsupported languages: Shows used source languages that are not supported by highlight.js as warnings or errors with the location of the used languages.
• Use supported styles: Allows to use all styles that are supported by highlight.js.
• Use custom styles: Use custom styles that are defined in the Antora UI bundle or defined via supplemental-ui.
• Use treeview: Use the highlight.js treeview language and style to show the files and folders with nice icons. See highlightjs-treeview for more information.
• Details are logged on info and debug log level.

Prerequisites

In order to use this extension, you must be using at least Node.js 16 and Antora 3. We assume you’ve already set up an Antora playbook file (i.e., antora-playbook.yml) to build your site.

Installation

Begin by installing the extension package into your playbook project:

$ npm i antora-highlightjs-extension

Usage

Register the extension

After installing the highlight.js extension package, you need to register the extension with Antora.

To register the extension, you’ll add an entry that cites the name of the package to the antora.extensions key in your Antora playbook file.

Open the Antora playbook file and add the extension as follows:

antora-playbook.yml

antora:
  extensions:
    - 'antora-highlightjs-extension'

In order to specify configuration keys for the extension, you must change the entry to a map syntax. When using the map syntax, the package name must be preceded by the require key, as shown here:

antora-playbook.yml

antora:
  extensions:
  - require: 'antora-highlightjs-extension'

You may want to start with this syntax so you don’t have to remember to switch to it later when you want to specify configuration.

Add handlebars templates

You have to change to 2 files in your Antora UI bundle or by overwriting via supplemental-ui:

• add {{> highlightjs-scripts }} to partials/footers-scripts.hbs
• add {{> highlightjs-styles }} partials/head-styles.hbs

Add to footers-scripts.hbs

<script id="site-script" src="{{{uiRootPath}}}/js/site.js" data-ui-root-path="{{{uiRootPath}}}"></script>
{{> highlightjs-scripts }}

{{> highlightjs-scripts }} will be replaced with the content of the file highlightjs-scripts.hbs that is generated by this extension.

Add head-styles.hbs

<link rel="stylesheet" href="{{{uiRootPath}}}/css/site.css">
{{> highlightjs-styles }}

{{> highlightjs-styles }} will be replaced with the content of the file highlightjs-styles.hbs that is generated by this extension.

Configuration

Minimal extension configuration

antora:
  extensions:
  - require: 'antora-highlightjs-extension'

Full extension configuration

antora:
  extensions:
    - require: "antora-highlightjs-extension"
      fail_on_unsupported_language: true # default: false => log warning messages
      languages: # default: [] => automatic
        - "javascript"
        - "shell"
        - "plaintext"
        - "asciidoc"
        - "java"
        - "treeview"
      style: "darcula" # default: "default"
      alias: # default: see below
        plaintext: ['txt', 'text']
        shell: ['bash', 'sh', 'console']
        javascript: ['js']
      treeview:
        enabled: true # default: true
        theme: "minimal" # default: "default"

Overview

Configuration key	Details
fail_on_unsupported_language	Default: false If set to true the extension will throw an exception when a language is used that is not supported by highlight.js. Otherwise it will only log a warning message.
languages	Default: [] => automatic If empty that indicates that the languages should be automatically detected. When defined it will use the defined languages and ignore the used languages. It will also fail when a used language is not defined in the languages list when fail_on_unsupported_language is set to true.
style	Default: default This defines the highlight.js style that should be used. * List of supported styles: Here. * Previews: Here
alias	Default: when not set the following aliases are used: Those aliases are used to map the language names that are used in the source blocks to the language names that are supported by highlight.js.
treeview/enabled	Default: true When set to true it will add the highlight.js treeview language and style. On false it will be skipped
treeview/theme	Default: default The highlight.js treeview theme that should be used. Currently we support default and minimal. More information can be found in the highlightjs-treeview project. More configuration options will be added in the future.

Examples

Setting alias for languages

alias:
  plaintext: ['txt', 'text']
  shell: ['bash', 'sh', 'console']
  javascript: ['js']

How it works

Process

• It registers an Asciidoctor extension (used-language-collector.js) that runs a Treeprocessor when the asciidoc files are processed.
  • collects all used languages from the source blocks and code blocks in the document,
  • stores it in an extensionContext that later can be read by the antora extension,
• On the event documentsConverted the highlight.js configuration is generated
  • copies the highlightjs-scripts.hbs into uiCatalog.
  • generates a highlightjs-styles.hbs with the defined style and copies it into the uiCatalog.
  • copies the highlight.js css into the uiCatalog.

    • copyies custom or used highlight.js style if not defined in the uiCatalog or supplemental-ui.

    • generates and copies a custom highlightjs-extension.css that overrides .doc pre.highlightjs > code.hljs

      📌 NOTE
      Overrides .doc pre.highlightjs > code.hljs with the same background color as defined in the style. Otherwise the antora ui bundle would always define the background color. In this case we want the highlight.js style to define the background color.

    • it tries to get the css from the highlight.js/styles package itself or gets the custom css from the uiCatalog or local path.

  • generates the highlight.js file highlight.bundle.js based on the defined and/or used languages.
    • registers the languages (defined or found or configured as alias)
  • writes out warning messages when a language is used that is not supported by highlight.js or throws an exception when configured (fail_on_unsupported_language: true).
    • uses browserfiy to combine the highlight.js files into one file => highlight.bundle.js
    • uses @browserify/uglifyify to minimize the highlight.bundle.js
    • copies the highlight.bundle.js into the uiCatalog

Generated Files

All generated files are first stored in .cache/antora-highlightjs-extension and then copied into the uiCatalog.

The following files are generated in .cache/antora-highlightjs-extension:

• css/highlightjs-extension.css
• js/vendor/highlight.bundle.js
• partials/highlghtjs-styles.hbs

css/highlightjs-extension.css

.doc pre.highlightjs > code.hljs {
  background: #f8f8f8; ①
}

• overrides the background color of the code blocks by using the bg color of the defined style

js/vendor/highlight.bundle.js

;(function () {
  'use strict'

  const hljs = require('highlight.js/lib/highlight')

  // registered languages ①
  hljs.registerLanguage('asciidoc', require('<project_path>/node_modules/highlight.js/lib/languages/asciidoc.js'))
  hljs.registerLanguage('plaintext', require('<project_path>/node_modules/highlight.js/lib/languages/plaintext.js'))
  hljs.registerLanguage('java', require('<project_path>/node_modules/highlight.js/lib/languages/java.js'))
  hljs.registerLanguage('javascript', require('<project_path>/node_modules/highlight.js/lib/languages/javascript.js'))
  hljs.registerLanguage('shell', require('<project_path>/node_modules/highlight.js/lib/languages/shell.js'))
  hljs.registerLanguage('xml', require('<project_path>/node_modules/highlight.js/lib/languages/xml.js'))
  hljs.registerLanguage('treeview', require('highlightjs-treeview/dist/js/treeview-default')) ②

  ;[].slice.call(document.querySelectorAll('pre code.hljs[data-lang]')).forEach(function (node) {
    hljs.highlightBlock(node)
  })

  global.hljs = hljs

})()

• registeres all languages that have been autodetected or defined in config.
• treeview is registered when enabled in config

partials/highlghtjs-styles.hbs

<link rel="stylesheet" href="{{{uiRootPath}}}/css/github.css"> ①
<link rel="stylesheet" href="{{{uiRootPath}}}/css/highlightjs-treeview.css"> ②
<link rel="stylesheet" href="{{{uiRootPath}}}/css/highlightjs-extension.css"> ③

• defined style (default: github)
• adds treeview style when it is enabled (default: enabled)
• additional extension that overrides the background color of the code blocks by using the bg color of the defined style

F.A.Q.

• Why using an old version of highlight.js?
  • The author of Antora pointed out some reasons why he is not using the latest version of highlight.js in Antora. See here for more information.

Ideas / Next steps

• Add more configuration options
  • use highlightjs-treeview to generate the file and folder icons into the ui catalog instead of putting all images into the css as data uris.
  • change highlightjs-treeview color of tree lines to the color of the style
• Change source blocks if type treeview from tabs and hashes (#) to asciitree so that it is rendered as a full treeview.
• Check how to integrate newer highlight.js versions into Antora.

Acknowledgements

• antora-lunr-extension that helped me to understand how to write an Antora extension and offered me a lot of inspiration.

Trademarks

AsciiDoc(R) is a trademark of the Eclipse Foundation, Inc.