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 |
---|---|---|---|
|
any theme name |
|
|
|
|
|
none/ |
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:
<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:
[source,ruby,linenum] --------------------- require 'sinatra' get '/hi' do "Hello World!" end ---------------------
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.