39. 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.

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

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

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: 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 in the source code blocks section.

Listing block with custom substitutions syntax
:version: 1.5.6.1

[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.6.1</version>
</dependency>

39.1. To Wrap or to Scroll

The default Asciidoctor stylesheet wraps long lines in listing and literal blocks by applying the CSS white-space: pre-wrap and word-wrap: break-word. The lines are wrapped at word boundaries, similar to how most text editors wrap lines. This prevents horizontal scrolling which some users considered a greater readability problem than line wrapping.

However, this behavior is configurable because there are times when you don’t want the lines in listing and literal blocks to wrap.

There are two ways to prevent lines from wrapping so that horizontal scrolling is used instead:

  • nowrap block option

  • unset the prewrap document attribute (on by default)

You can use the nowrap option on literal or listing blocks to prevent lines from being wrapped in the HTML.

Listing block with nowrap option syntax
[source%nowrap,java]
----
public class ApplicationConfigurationProvider extends HttpConfigurationProvider
{
   @Override
   public Configuration getConfiguration(ServletContext context)
   {
      return ConfigurationBuilder.begin()
               .addRule()
               .when(Direction.isInbound().and(Path.matches("/{path}")))
               .perform(Log.message(Level.INFO, "Client requested path: {path}"))
               .where("path").matches(".*");
   }
}
----

When the nowrap option is used, the nowrap class is added to the <pre> element. This class changes the CSS to white-space: pre and word-wrap: normal.

Result: Listing block with nowrap option applied
public class ApplicationConfigurationProvider extends HttpConfigurationProvider
{
   @Override
   public Configuration getConfiguration(ServletContext context)
   {
      return ConfigurationBuilder.begin()
               .addRule()
               .when(Direction.isInbound().and(Path.matches("/{path}")))
               .perform(Log.message(Level.INFO, "Client requested path: {path}"))
               .where("path").matches(".*");
   }
}

To prevent lines from wrapping globally, unset the prewrap attribute on the document.

Disable prewrap globally (thus, enabling nowrap)
:prewrap!:

When the prewrap attribute is unset, the nowrap class is added to any <pre> elements.

Now, you can use the line wrapping strategy that works best for you and your readers.