The AsciiDoc distribution includes a source filter for highlighting code syntax.
DocBook Outputs
AsciiDoc encloses the source code in a DocBook programlisting element and leaves source code highlighting to the DocBook toolchain (dblatex has a particularly nice programlisting highlighter). The DocBook programlisting element is assigned two attributes:
- 
The language attribute is set to the AsciiDoc language attribute. 
- 
The linenumbering attribute is set to the AsciiDoc src_numbered attribute (numbered or unnumbered). 
HTML Outputs
You have the choice of three HTML source code highlighters, your selection is determined by the source-highlighter attribute (defaults to source-highlight):
| Note | Set the source-highlighter attribute from the asciidoc(1)command-line or in the document header (not in the document body,
because the configuration file conditional macros are processed at
load time). | 
GNU Source Highlight
The default highlighter is the GNU source-highlight which can highlight html4, html5 and xhtml11 outputs. The GNU source-highlight must be installed and the source-highlight command must reside in the shell search PATH.
Highlight
You can use Highlight syntax highlighter for xhtml11, html5 and html4 outputs (set the source-highlighter attribute to highlighter).
- 
The highlight command must reside in the shell search PATH. 
- 
To make Highlighter your default highlighter put the following line your ~/.asciidoc/asciidoc.conffile:source-highlighter=highlight
- 
The AsciiDoc encoding attribute is passed to Highlighter using the --encodingcommand-line option.
Pygments
The Pygments syntax highlighter can be used for xhtml11 and html5 outputs (set the source-highlighter attribute to pygments).
- 
The pygmentize command must reside in the shell search PATH. 
- 
You can customize Pygments CSS styles by editing ./stylesheets/pygments.css. Thepygments.cssCSS file was generated with:from pygments.formatters import HtmlFormatter print HtmlFormatter().get_style_defs('.highlight')
- 
To make Pygments your default highlighter put the following line your ~/.asciidoc/asciidoc.conffile:source-highlighter=pygments
- 
The AsciiDoc encoding attribute is passed to Pygments using the -Ocommand-line option.
Block attributes
The following attributes can be included in source code block attribute lists.
- 
style and language are mandatory. 
- 
style, language and src_numbered are the first three positional attributes in that order. 
- 
The args attribute allows the inclusion of arbitrary (highlighter dependent) command options. 
- style
- 
Set to source. 
- language
- 
The source code language name. NoteThe language names vary between highlighters — consult the selected highlighter manual. 
- src_numbered
- 
Set to numbered to include line numbers. 
- src_tab
- 
Set tab size (GNU source-highlight only). 
- args
- 
Include this attribute value in the highlighter command-line (HTML outputs) or in the programlistingelement (DocBook).
Testing
Test the filter by converting the test file to HTML with AsciiDoc:
$ asciidoc -v ./filters/source/source-highlight-filter-test.txt
$ firefox ./filters/source/source-highlight-filter-test.html &Examples
Source code paragraphs
The source paragraph style will highlight a paragraph of source
code. These three code paragraphs:
[source,python]
if n < 0: print 'Hello World!'
:language: python
[source]
if n < 0: print 'Hello World!'
[source,ruby,numbered]
[true, false].cycle([0, 1, 2, 3, 4]) do |a, b|
    puts "#{a.inspect} => #{b.inspect}"Render this highlighted source code:
if n < 0: print 'Hello World!'
if n < 0: print 'Hello World!'
1: [true, false].cycle([0, 1, 2, 3, 4]) do |a, b| 2: puts "#{a.inspect} => #{b.inspect}"
Unnumbered source code listing
This source-highlight filtered block:
 [source,python]
 ---------------------------------------------------------------------
 ''' A multi-line
     comment.'''
 def sub_word(mo):
     ''' Single line comment.'''
     word = mo.group('word')   # Inline comment
     if word in keywords[language]:
         return quote + word + quote
     else:
         return word
 ---------------------------------------------------------------------Renders this highlighted source code:
''' A multi-line comment.''' def sub_word(mo): ''' Single line comment.''' word = mo.group('word') # Inline comment if word in keywords[language]: return quote + word + quote else: return word
Numbered source code listing with callouts
This source-highlight filtered block:
 [source,ruby,numbered]
 ---------------------------------------------------------------------
 #
 # Useful Ruby base class extensions.
 #
 class Array
   # Execute a block passing it corresponding items in
   # +self+ and +other_array+.
   # If self has less items than other_array it is repeated.
   def cycle(other_array)  # :yields: item, other_item
     other_array.each_with_index do |item, index|
       yield(self[index % self.length], item)
     end
   end
 end
 if $0 == __FILE__                                 # <1>
   # Array#cycle test
   # true => 0
   # false => 1
   # true => 2
   # false => 3
   # true => 4
   puts 'Array#cycle test'                         # <2>
   [true, false].cycle([0, 1, 2, 3, 4]) do |a, b|
     puts "#{a.inspect} => #{b.inspect}"
   end
 end
 ---------------------------------------------------------------------
 <1> First callout.
 <2> Second callout.Renders this highlighted source code:
1: # 2: # Useful Ruby base class extensions. 3: # 4: 5: class Array 6: 7: # Execute a block passing it corresponding items in 8: # +self+ and +other_array+. 9: # If self has less items than other_array it is repeated. 10: 11: def cycle(other_array) # :yields: item, other_item 12: other_array.each_with_index do |item, index| 13: yield(self[index % self.length], item) 14: end 15: end 16: 17: end 18: 19: if $0 == __FILE__ # <1> 20: # Array#cycle test 21: # true => 0 22: # false => 1 23: # true => 2 24: # false => 3 25: # true => 4 26: puts 'Array#cycle test' # <2> 27: [true, false].cycle([0, 1, 2, 3, 4]) do |a, b| 28: puts "#{a.inspect} => #{b.inspect}" 29: end 30: end
- 
First callout. 
- 
Second callout. 
| Tip | 
 |