A demonstration of the modded HighlightTreeprocessor extension with some usage instructions.

Associated files:

Highlighting Previews

A couple of examples of how the rendered code looks like. The custom CSS stylesheet defines a default theme plus some dedicated themes targeting specific syntaxes.

Example 1

For PureBasic code I’ve defined a dedicated theme mimicing the native IDE of the language.

; ==============================================================================
;                   PureBasic 5.62 - Syntax Highlighting Test
; ==============================================================================
; by Tristano Ajmone (2018/10/04), public domain: http://unlicense.org

Declare.i CountdownDialog(text.s)

Macro IsEven(num)
  (num & 1 = 0)
EndMacro

For i=5 To 1 Step -1
  If isEven(i) : Debug Str(i) +" is even." : EndIf
  TEXT$ = "Iteration number: " + Str(i) + ~"\n\nDo you wish to continue?"
  If CountdownDialog(TEXT$) : Break : EndIf
Next

MyVar = %1011 << 1
EnableASM
INC MyVar ; Mix ASM keywords with PureBasic variable
DisableASM
Debug "MyVar: "+Str(MyVar)

Procedure.i CountdownDialog(text.s)
  UserChoice = MessageRequester("Countdown Dialog", text, #PB_MessageRequester_YesNo |
                                                          #PB_MessageRequester_Info)
  If UserChoice = #PB_MessageRequester_No
    CompilerIf #PB_Compiler_Processor = #PB_Processor_x64
      !mov rax,1
    CompilerElse
      !mov eax,1
    CompilerEndIf
  Else
    ProcedureReturn 0
  EndIf
  ProcedureReturn ; RAX/EAX will be the implicit return value
EndProcedure

Example 2: Line Numbers

In this example we add the linenum option to enable line-numbering. Again, for the Alan syntax there is a dedicated CSS theme.

 1 --==============================================================================
 2 -- "Chez Alan" by Tristano Ajmone, 2018 || Public domain: http://unlicense.org
 3 --==============================================================================
 4 Import 'library.i'. --> ALAN Standard Library v2.1
 5 
 6 The my_game IsA definition_block
 7   Has title    "Chez Alan".
 8   Has subtitle "A small demo adventure".
 9   Has author   "Tristano Ajmone".
10   Has year     2018.
11   Has version  "1".
12 End The.
13 
14 The 'IF Plaza' IsA location
15   Exit north to ChezAlan.
16   Description "North lies ""Chez Alan"", the renown French brasserie."
17 End The 'IF Plaza'.
18 
19 The ChezAlan IsA room.
20   Name 'Chez Alan Brasserie'.
21   Description
22     "Today Chez Alan seems busier then ever."
23   Entered
24     """Welcome back Sir!"" the maitre greets you.
25     $nHe has a strong French accent."
26 End The ChezAlan.
27 
28 The Pierre IsA male At ChezAlan.
29   Name Pierre.
30   Name 'Alan''s' brother.
31   Is named.
32   Has ex "Pierre is Alan's brother.".
33 End The Pierre.
34 
35 Start At 'IF Plaza'.
36 Describe banner.

When linenums is used, Highlight is invoked with the -l -j 2 options.

Example 3: Substitutions

In this example we’ll enable substitutions inside the listing code via the subs=quotes option.

Asciidoc source
[source,alan,subs=quotes]
------------------------
The 'dance hall' #IsA location#
  Description
    "The hall is #_bigger_ than you expected#, and
     far too crowded. You feel the urge to leave."
End the.
------------------------
HTML result
The 'dance hall' IsA location
  Description
    "The hall is bigger than you expected, and
     far too crowded. You feel the urge to leave."
End the.

Text enclosed within single or double # symbols will be wrapped in the <mark> tag (See Asciidoctor Manual ยง19.5), which I’ve customized to mimic a smeared fluorescent marker. Also notice how the word ‘bigger’ is rendered as emphasized text.

Usage Instructions

To enable the modded HighlightTreeprocessor extension you must invoke Asciidoctor with the -r (--require) option:

asciidoctor \
  -r ./highlight-treeprocessor_mod.rb \
  -a source-highlighter=highlight \
  -a docinfo=shared \
  -T haml \
  example_mod.asciidoc

To enable using Highlight, you need to set the source-highlighter attribute to highlight. You may do so via the command line, using the -a (--attribute) option:

asciidoctor \
  -r ./highlight-treeprocessor_mod.rb \
  -a source-highlighter=highlight \
  -a docinfo=shared \
  -T haml \
  example_mod.asciidoc

or you can set the source-highlighter attribute inside the document header:

:source-highlighter: highlight

Custom CSS Stylesheets

Because the modded extension doesn’t rely on Highlight to convert themes to CSS, you’ll need to add to the output document your custom CSS.

The easiest way to do so without interfering with the native stylesheet of the Asciidoctor HTML backend is to incorporate the CSS file via a head docinfo file, and then enable it via the docinfo attribute, either in the document header:

:docinfo: shared

or via CLI options:

asciidoctor \
  -r ./highlight-treeprocessor_mod.rb \
  -a source-highlighter=highlight \
  -a docinfo=shared \
  -T haml \
  example_mod.asciidoc

The docinfo.html file used for this document contains a single header line to load the external CSS stylesheet:

<link rel="stylesheet" href="highlight_mod.css">

Further more, if you want to be able to customize themes on a per language base, and use different background colors for each theme, you’ll need to use the customized Haml template provided with this example:

and tell Asciidoctor where to look for the custom templates folder via the -T (--template-dir) option:

asciidoctor \
  -r ./highlight-treeprocessor_mod.rb \
  -a source-highlighter=highlight \
  -a docinfo=shared \
  -T haml \
  example_mod.asciidoc

The customized template ensures that the lang attribute is added also to the <pre> tag, so it might be targeted via custom CSS:

<pre class="highlight" lang="alan">
  <code class="language-alan" data-lang="alan">

whereas by default Asciidoctor will only emit the lang attribute on the <code> tag:

<pre class="highlight">
  <code class="language-alan" data-lang="alan">

In the /sass/ folder you’ll find the commented SCSS sources used by this document, and a useful Sass template for quickly generating Highlight themes targeting specific syntaxes.

Custom LangDefs

If you’d like to make available to Highlight some custom langDefs, or override the native language definitions of Highlight with your same-named customized versions, you only need to set the HIGHLIGHT_DATADIR environment variable to point to your custom Hihglight settings folder before invoking Asciidoctor.

The modded extension will check if the HIGHLIGHT_DATADIR environment variable is set, and if it is it will enforce it by invoking Highlight with the --data-dir=<HIGHLIGHT_DATADIR> option so that it gets the highest override priority.

This ensures that custom langDefs inside HIGHLIGHT_DATADIR will always override the predefined ones, whereas ordinarily the path of the HIGHLIGHT_DATADIR env var would be searched after Highlight installation folder.

Since it’s not possible to control the --data-dir option from within AsciiDoc documents, this hardcoded workaround is a convenient solution for projects which need to override Highlight default configurations.