On this page, you’ll learn:
How to create an AsciiDoc source block.
How to specify a source language for a source block.
How to specify a global source language using
How to disable syntax highlighting for source blocks.
What’s a source block?
An AsciiDoc source code block, or source block for short, displays snippets of content that are written in a given programming, data, configuration, or markup language.
The content of a source block is colorized using a syntax highlighter when it’s rendered in a site.
A source block is created by assigning the attribute
source and the name of a valid source language to a block.
source and source language attributes
source is a positional element attribute.
It’s assigned to a block using the first position in an attribute list.
|1||An attribute list with
The name of a source language is assigned to the second position in an attribute list or using the
source-language document attribute.
The source language is the name of a programming, data, configuration, or markup language in which the block’s content is written.
Specifying a source language serves two purposes.
First, it communicates to the site visitor which language runtime or data format reader is needed to interpret the code displayed in the block.
Second, it allows a syntax highlighter to colorize the source content properly, such as emphasizing language types and keywords.
Finally, by assigning a language to a block, you can implicitly assign
source to the block at the same time.
As shown in Example 2, by assigning the name of a valid source language to the second position of an attribute list, you implicitly assign
source to the first position.
|1||To assign a source language to the second position of an attribute list without assigning
The language name is written in lowercase letters and must be a language recognized by the syntax highlighter Antora uses for the content to be colorized correctly. If most of your source blocks use the same language, you can assign the name of the language to the source-language document attribute.
source is specified but a language isn’t specified in the attribute list of a source block or by the
source-language document attribute, Antora applies the language
none at runtime.
The block is styled like other source blocks, but no syntax highlighting will be applied to its content.
Create a source block
Source blocks are most often created from delimited listing and literal blocks as well as paragraphs. A block becomes a source block in the following scenarios:
a language name is assigned to the second position in a block’s attribute list, which implicitly assigns
sourceto the first position in the attribute list
sourceis assigned directly to the first position in a block’s attribute list, and a language name is assigned to the second position or to the
the document attribute
source-languageis set, which automatically promotes all delimited listing blocks that aren’t assigned another style to source blocks
source is assigned to a block using any of these methods, the content of the block is colorized according to the assigned source language by the syntax highlighter.
Assign source implicitly
source is assigned to a block using the first position of an attribute list, you can assign it implicitly by entering a comma (
,) directly after the opening bracket, followed by the name of a source language.
The comma is required, otherwise the language would be assigned to the first position of the attribute list.
Example 3 shows the
source attribute being applied implicitly to a listing block.
[,name-of-language] (1) --(2) Content of source block (3) Content of source block Content of source block --(4)
|1||Directly after the opening square bracket (
|2||On the new line directly below the attribute list, enter the opening delimiter of a listing block (
|3||On the lines below the opening delimiter, insert your code snippet.|
|4||On a new line, enter the closing delimiter of the listing block (
You can use
source implicitly on other block types to create a source block.
Example 4 shows the
source attribute being applied implicitly to a paragraph.
A regular paragraph. [,name-of-language] (1) Content of source block (2) A regular paragraph.
|1||After the opening square bracket (
|2||On the line directly below the attribute list, enter the block’s content on one or more continuous lines.|
In Example 5,
source is assigned implicitly and
haskell is assigned as the language.
[,haskell] ---- main :: IO () main = putStrLn "Hello, World!" ----
Example 6 shows how the source block appears when displayed in a site.
main :: IO () main = putStrLn "Hello, World!"
The content in Example 6 is colorized, and when you hover over the block, the language name HASKELL appears in its upper right corner.
Assign source directly
In some cases, you may prefer to assign
source directly to a block.
In a block’s attribute list,
source is entered in the first position in the list, followed by a comma (
,), and then the name of a language, such as
Example 7 shows the
source attribute being applied directly to a delimited literal block (
[source,name-of-language] (1) .... Content of source block Content of source block Content of source block ....
|1||In the attribute list, assign
In Example 8,
source is assigned to the first position and
sql is assigned as the language to the second position.
[source,sql] ---- IF EXISTS (SELECT name FROM myobjects WHERE name = 'hello') ----
Example 9 shows how the source block appears when displayed in a site.
IF EXISTS (SELECT name FROM myobjects WHERE name = 'hello')
The content in Example 9 is colorized, and when you hover over the block, the language name SQL appears in the upper right corner.
To assign an element ID, role, or option to a source block using their applicable shorthand syntax, specify the
source attribute and append the ID, role, or options to the attribute.
Example 10 shows the
source attribute and an element ID being assigned to a listing block.
[#element-id,name-of-language] (1) (2) ---- Content of source block Content of source block ----
|1||In the attribute list, specify the element ID in the first position.
An element ID is directly appended to the style (which is empty in this case) using the hash symbol (
|2||Directly after the element ID, enter a comma (
Now let’s look at a source block that’s created with a delimited literal block and is assigned an element ID using the shorthand hash symbol (
In Example 11, an element ID is appended to the implicit
source style with a
The line comparison syntax,
diff, is assigned to the second position.
[#temper-change,diff] .... - temperDestination(destination) + if (destination instanceof Boom) moderateDestination(destination) } rootLoggerHolder.set(undefined, addFailOnExitHooks(logger, failureLevel)) ....
Example 12 shows how the source block appears when displayed in a site.
- temperDestination(destination) + if (destination instanceof Boom) moderateDestination(destination) } rootLoggerHolder.set(undefined, addFailOnExitHooks(logger, failureLevel))
The content in Example 12 is colorized, and when you hover over the block, the language name DIFF appears in the upper right corner of the block.
Promote listing blocks with source-language
You can define a source language globally, either at the page, component version, or site level, by setting the
source-language document attribute.
source-language is set, all delimited listing blocks that aren’t assigned a style are automatically promoted to source blocks.
source-language attribute is set and assigned a value in the document header of a page, component version descriptor file, or playbook.
In Example 13, the
source-language attribute is set in the header of a page and assigned the name of a language.
= Title of Page :source-language: name-of-language (1) A paragraph. --(2) Content of source block --(2) A paragraph. .... (3) Content of a literal block. .... (3)
|1||On a new line in the header of the page, set the built-in document attribute
|3||This literal block remains a literal block.
Only listing blocks are automatically promoted to source blocks when
source-language is set, you may want some listing blocks to not be promoted to source blocks or to assign a different language to a few of them.
Example 14 shows how to prevent a listing block from being promoted to a source block and how to override the language assigned to the
= Title of Page :source-language: java (1) A paragraph. --(2) Content of source block --(2) A paragraph. [listing] (3) ---- Content of listing block ---- [,yaml] (4) ---- Content of source block ----
|1||The document attribute
|2||This listing block is automatically promoted to a source block and assigned the language
|3||This listing block is assigned the style
|4||This source block is directly assigned the language
We’ll look at how colorization gets added in the next section.
Syntax highlighting is a technique of colorizing the code to make it easier to read by emphasizing types, keywords, and other language constructs.
Syntax highlighting of source blocks is enabled using the
source-highlighter site-wide by default (see site and configuration attributes), therefore, you don’t need to do anything to enable this feature.
Antora uses highlight.js to automatically add syntax highlighting to source blocks that specify a source language.
You can disable or override the
source-highlighter attribute in the playbook or a component version descriptor.
To disable syntax highlighting, unset the
source-highlighter attribute in your playbook.
asciidoc: attributes: source-highlighter: ~
Currently, the only
source-highlighter value Antora supports when using the reference UI is
If you set the value to
coderay, Antora will fail.
That’s because these built-in, build-time syntax highlighters are not available in the Antora environment (and specifically Asciidoctor.js).
You can use other client-side (also known as browser) libraries, such as prettify or prism. However, to use them, you’ll need to modify the UI to bundle and add the library to each page, like the reference UI does for highlight.js.
In the future, it will be possible to register additional adapters to plug in other syntax highlighters. However, that feature is not currently available in Antora.
The content of a source block is often inserted using an include directive. See Include an Example to learn more.