Listing Blocks

Blocks and paragraphs assigned the listing style display their rendered content exactly as you see it in the source. Listing content is converted to preformatted text (i.e., <pre>). The content is presented in a fixed-width font and endlines are preserved. Only special characters and callouts are replaced when the document is converted.

The listing style can be applied to content using one of the following methods:

  • setting the listing style on a block or paragraph using an attribute list, or

  • enclosing the content within a pair of listing block delimiters (----).

Listing style syntax

The block style listing can be applied to a block or paragraph, by setting the attribute listing using an attribute list.

Example 1. Listing style syntax
[listing]
This is an example of a paragraph assigned
the `listing` style in an attribute list.
Notice that the monospace marks are
preserved in the output.

The result of Example 1 is rendered below.

This is an example of a paragraph assigned
the `listing` style in an attribute list.
Notice that the monospace marks are
preserved in the output.

Delimited listing block

A delimited listing block is surrounded by lines composed of four hyphens (----). This method is useful when the content contains empty lines.

Example 2. Delimited listing block syntax
----
This is a _delimited listing block_.

The content inside is displayed as <pre> text.
----

Here’s how the block in Example 2 appears when rendered.

This is a _delimited listing block_.

The content inside is displayed as <pre> text.

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

  • The HTML element <pre> is escaped, that is, it’s displayed verbatim, not interpreted.

  • The endlines are preserved.

  • The phrase delimited listing block isn’t italicized, despite having the underscore formatting marks around it.

Listing blocks are good for displaying snippets of raw source code, especially when used in tandem with the source style and source-highlighter attribute. See Source Code Blocks to learn more about source and source-highlighter.

Listing substitutions

Content that is assigned the listing style, either via the explicit block style or the listing delimiters is subject to the verbatim substitution group. Only special characters and callouts are replaced automatically in listing content.

You can control the substitutions applied to a listing block using the subs attribute.

Example 3. Delimited listing block with custom substitutions syntax
[subs="+attributes"]
----
This is a _delimited listing block_
with the `subs` attribute assigned
the incremental value `+attributes`.
This attribute reference:

{replace-me}

will be replaced with the attribute's
value when rendered.
----

The result of Example 3 is rendered below.

This is a _delimited listing block_
with the `subs` attribute assigned
the incremental value `+attributes`.
This attribute reference:

I've been replaced!

will be replaced with the attribute's
value when rendered.

See Customize the Substitutions Applied to Blocks to learn more about the subs attribute and how to apply incremental substitutions to listing content.