Source Highlighting

Source highlighting is applied to text that’s assigned the source block style and a language. You can define the source language directly on the block or globally using the source-language document attribute.

source-highlighter attribute

Source highlighting isn’t enabled by default. To enable source highlighting, you must set the source-highlighter attribute in the document header using an attribute entry.

= Document Title
:source-highlighter: <value>

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

= Document Title
:source-highlighter: rouge

You can also declare this attribute using the CLI or API.

Available source highlighters

Table 1 lists the recognized values for the source-highlighter attribute and the toolchains that support the usage of the syntax highlighting libraries.

Table 1. Built-in source-highlighter values and the supporting toolchains
Library	Value	Toolchain
CodeRay	`coderay`	Asciidoctor, AsciidoctorJ, Asciidoctor PDF
highlight.js	`highlight.js`	Asciidoctor, AsciidoctorJ, Asciidoctor.js
Pygments	`pygments`	Asciidoctor, Asciidoctor PDF
Rouge	`rouge`	Asciidoctor, AsciidoctorJ, Asciidoctor PDF

To use Rouge, CodeRay, or Pygments, you must have the appropriate library installed on your system. See Rouge, CodeRay, or Pygments for installation instructions.

If you’re using the client-side library Highlight.js, there’s no need to install additional libraries. The generated HTML will load the required source files from a CDN, custom URL, or file path.

Source Highlighter vs. Syntax Highlighter

You might notice that the source-highlighter attribute uses the term “source highlighter”, whereas the library that performs the highlighting is referred to as a “syntax highlighter”. What’s the difference?

The generally accepted term for a syntax (aka code) highlighter is “syntax highlighter”.
The syntax highlighter is applied to source blocks in AsciiDoc, hence why we say “source highlighter”.

In other words, the source-highlighter attribute means “use this syntax highlighter to colorize source blocks”.

Apply source highlighting

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

Example 1. Source block with title and source highlighting

[source#hello,ruby] (1) (2) (3)
--(4)
require 'sinatra'

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

1	Assign the block style `source` to the first position in the attribute list.
2	An optional ID can be added to the block by appending it to style using the shorthand syntax (`#`) for `id`.
3	Assign a source language to the second position.
4	The source style is typically assigned to delimited listing blocks.

The result of Example 1 is displayed below.

require 'sinatra'

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

Example 2. Source style

[source,xml] (1)
<meta name="viewport"
  content="width=device-width, initial-scale=1.0">
(2)
This is normal content.

1	Place the attribute list directly on the paragraph.
2	Once an empty line is encountered the syntax highlighting is unset.

The result of Example 2 is displayed below.

<meta name="viewport"
  content="width=device-width, initial-scale=1.0">

This is normal content.

Disable source highlighting

To disable source highlighting for a given source block, specify the language as text or remove the source style.

source-language attribute

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.

Example 3. Set source-language attribute

= Document Title
: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 on an individual block by specifying a source language after source.

Example 4. Override source-language attribute

= Document Title
:source-highlighter: pygments
:source-language: java

[source,ruby]
require 'sinatra'