Source Code Blocks

Developers are accustomed to seeing source code that uses color and other styling to emphasize the code’s structure (i.e., keywords, types, delimiters, etc.). This technique is known as syntax highlighting source code (or source highlighting, for short). Since this technique is so prevalent—​one could say expected—​Asciidoctor integrates a wealth of libraries to syntax highlight source code blocks in your document. This list includes CodeRay, Pygments, highlight.js, and prettify.

Enabling source highlighting

When enabled, syntax highlighting gets applied to listing or literal blocks that have the source block style and a source language. However, syntax highlighting is not enabled by default.

To enable syntax highlighting in a document, you must set the source-highlighter document attribute. You can set this attribute in the document or from the CLI or API.

If you set the attribute in the document, it must be defined in the document header.

= Document Title
:source-highlighter: <value>

For example, here’s how to enable syntax highlighting using CodeRay:

= Document Title
:source-highlighter: coderay

Available source highlighters

The following table lists the recognized values for the source-highlighter attribute.

Recognized values and supported environments for the source-highlighter attribute
Library Name Attribute Value Supported Environments

CodeRay

coderay

Asciidoctor, AsciidoctorJ, Asciidoctor PDF

highlight.js

highlightjs

Asciidoctor, AsciidoctorJ, Asciidoctor.js

prettify

prettify

Asciidoctor, AsciidoctorJ, Asciidoctor.js

Pygments

pygments

Asciidoctor, Asciidoctor PDF

Rouge

rouge

Asciidoctor PDF

To use CodeRay, Pygments, or Rouge, you must have the appropriate library installed on your system. See CodeRay or Pygments to find installation instructions. (We don’t yet have a section about Rouge).

On the other hand, if you’re using a client-side syntax highlighting library like highlight.js or prettify, there’s no need to install additional libraries. The generated HTML will load the required source files from a CDN (or custom URL or file path).

Applying source highlighting

To apply highlighting to source code, you must add the source block style to a listing block, literal block, or paragraph and also specify a source language.

Code block with title and syntax highlighting
.app.rb (1)
[#src-listing] (2)
[source,ruby] (3) (4)
---- (5)
require 'sinatra'

get '/hi' do
  "Hello World!"
end
----
1 An optional title can be added to the block.
2 An optional ID can be added to the block.
3 Assign the block name source to the first position in the attribute list.
4 Assign a source language to the second position.
5 The source block name is typically assigned to listing and literal blocks.
Result: Source block with title and syntax highlighting
app.rb
require 'sinatra'

get '/hi' do
  "Hello World!"
end
Source style
[source,xml] (1)
<meta name="viewport"
  content="width=device-width, initial-scale=1.0">

This is normal content.  (2)
1 Place the attribute list directly on the paragraph
2 Once an empty line is encountered the syntax highlighting is unset.
Result: Source style
<meta name="viewport"
  content="width=device-width, initial-scale=1.0">

This is normal content.

If the majority of your source blocks use the same source language, you can set the source-language attribute in the document header and assign a language to it.

Source language attribute
:source-highlighter: pygments
:source-language: java

[source]
----
public void setAttributes(Attributes attributes) {
    this.options.put(ATTRIBUTES, attributes.map());
}
----

You can override the global source language by specifying a source language on the block.

[source,ruby]
require 'sinatra'

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

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