Source Code Blocks

Developers are accustomed to seeing source code colorized to emphasize the code’s structure (i.e., keywords, types, delimiters, etc.). This technique is known as syntax highlighting. Since this technique is so prevalent, Asciidoctor integrates with a number of libraries to syntax highlight the source code blocks in your document. The list of integrated libraries includes Rouge, CodeRay, Pygments, and highlight.js.

Example 1 shows a listing block with the source style and language ruby applied to its content.

Example 1. Source block syntax

[source,ruby]
----
require 'sinatra'

get '/hi' do
  "Hello World!"
end
----

The result of Example 1 is rendered below.

require 'sinatra'

get '/hi' do
  "Hello World!"
end

Using include directives in source blocks

You can use an include directive to insert source code into an AsciiDoc document directly from a file.

Example 2. Code inserted from another file

[source,ruby]
----
include::app.rb[]
----

If you specify custom substitutions on the source block using the subs attribute, make sure to include the specialcharacters substitution if you want to preserve syntax highlighting. However, if you do plan to modify the substitutions, we recommend using incremental substitutions instead.