Listing Blocks

Like literal blocks, the content in listing blocks is displayed exactly as you entered it. Listing block content is converted to <pre> text. The content in listing blocks is only subject to special character and callout substitutions.

The listing block name can be applied to content two ways.

  1. Set the listing attribute on the element.

  2. Contain the content within a delimited listing block.

Listing style syntax

The listing block name is applied to an element, such as a paragraph, by setting the listing attribute on that element.

Listing style syntax
[listing]
This is an example of a paragraph styled with `listing`.
Notice that the monospace markup is preserved in the output.
Result: Listing style
This is an example of a paragraph styled with `listing`.
Notice that the monospace markup is preserved in the output.

Delimited listing block

A delimited listing block is surrounded by lines composed of four hyphens (----).

Delimited listing block syntax
----
This is an example of a _listing block_.
The content inside is displayed as <pre> text.
----

Here’s how the block above appears when rendered as HTML.

Result: Delimited listing block
This is an example of a _listing block_.
The content inside is displayed as <pre> text.

You should notice a few things about how the content is processed.

  • the HTML tag <pre> is escaped

  • then endlines are preserved

  • the phrase listing block is not italicized, despite having underscores around it.

Listing blocks are good for displaying raw source code, especially when used in tandem with the source and source-highlighter attributes. The example below shows a listing block with source and the language ruby applied to its content.

Source block syntax
.app.rb
[source,ruby]
----
require 'sinatra'

get '/hi' do
  "Hello World!"
end
----
Result: Listing block with the source attribute set
app.rb
require 'sinatra'

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

Detailed instructions for using the source and source-highlighter attributes are provided on the source code paragraphs and blocks page.

Listing block with custom substitutions syntax
:version: 1.5.7

[source,xml,subs="verbatim,attributes"]
----
<dependency>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-java-integration</artifactId>
  <version>{version}</version>
</dependency>
----
Result: Listing block with custom substitutions applied
<dependency>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-java-integration</artifactId>
  <version>1.5.7</version>
</dependency>