A demonstration of the original HighlightTreeprocessor extension published on the Asciidoctor Extensions Lab project.

Highlighting Previews

A couple of examples of how the rendered code looks like.

Associated files:

Example 1

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

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

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

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

Example 2: Line Numbers

Now we add the linenum option to enable line-numbering:

 1 --==============================================================================
 2 -- "Chez Alan" by Tristano Ajmone, 2018 || Public domain: http://unlicense.org
 3 --==============================================================================
 4 Import 'library.i'. --> ALAN Standard Library v2.1
 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.
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'.
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.
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.
35 Start At 'IF Plaza'.
36 Describe banner.

Usage Instructions

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

asciidoctor -r ./highlight-treeprocessor.rb your_document.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.rb \
  -a source-highlighter=highlight \

or you can declare the attribute inside the document header:

:source-highlighter: highlight

Highlight Options

Theme and Style

The original extension exposes two attributes to set the Highlight theme and to control the CSS styling format:

attribute name allowed values default value Highlight option


any theme name







The highlight-style attribute allows you to choose any Highlight theme by setting its value to the theme’s filename (without the extension). The selected theme must be inside Highlight /themes/ folder.

The HighlightTreeprocessor extension only allows you to pick a single theme per document.

By default, Asciidoctor will set highlight-css to class, so that Highlight will use class names to style the various syntax elements (which is also Highlight default behavior):

<span class="hl kwa">require</span>

whereas setting highlight-css to style will inline the CSS definitions into the tags, instead of using classes (i.e. Highlight is invoked with the --inline-css option):

<span style="color:#62acce; font-weight:bold">require</span>

Obviously, the latter solution is more verbose, so you’re better off not setting the highlight-css attribute at all, and just stick to the extension default value (class).

The style option fails to style the background color (i.e. Highlight canvas), probably due to the extension being very old and Highlight having changed tag/classes in the HTML output.

When highlight-css is set to class, the extension will get the CSS stylesheet of the highlight-style theme by invoking Highlight with the -c stdout --print-style -s option, and injects it at the end of the output HTML document:

HTML Example
/* Style definition file generated by highlight 3.49, http://www.andre-simon.de/ */
/* highlight theme: vim kellys */
body.hl { background-color:#2a2b2f; }
.listingblock pre.highlight { background-color:#2a2b2f; }
pre.highlight>code { color: #e1e0e5; }
.hl.num { color:#dabc7f; }
.hl.esc { color:#9ab2c8; }
.hl.str { color:#dabc7f; }
.hl.pps { color:#dabc7f; }
.hl.slc { color:#67686b; }
.hl.com { color:#67686b; }
.hl.ppc { color:#77cf63; }
.hl.opt { color:#e1e0e5; }
.hl.ipl { color:#c75e75; }
.hl.lin { color:#a3a362; }
.hl.kwa { color:#62acce; font-weight:bold; }
.hl.kwb { color:#e6ac32; }
.hl.kwc { color:#cf8563; }
.hl.kwd { color:#bb63cf; }

Line Numbering

Furthermore, you can enable line-numbering via the linenums option to the source block style of a listing block:

AsciiDoc Example
require 'sinatra'

get '/hi' do
  "Hello World!"
Result Preview
 1 require 'sinatra'
 3 get '/hi' do
 4   "Hello World!"
 5 end

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