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

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

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 \
  your_document.asciidoc

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

highlight-style

any theme name

edit-eclipse

--style=<value>

highlight-css

class/style

class

none/--inline-css

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>
/* 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; }
</style>
</body>
</html>

Line Numbering

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

AsciiDoc Example
[source,ruby,linenum]
---------------------
require 'sinatra'

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

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